Getting started

The CloudMC API allows you to manage your environments and provision resources in a simple programmatic way using standard HTTP requests.

The API is RESTful. Responses, successful or not, are returned in JSON. Request bodies must be JSON, and should be made over SSL.

API endpoint : https://cloudmc_endpoint/api/v1

Authentication

## To authenticate, add a header
## Make sure to replace `your_api_key` with your API key.
curl "https://cloudmc_endpoint/api/v1/organizations" \
   -H "MC-Api-Key: your_api_key"

API endpoints are secured by the same role-based access control (RBAC) as the CloudMC portal. To identify who is making the requests, it is required to add a header to your HTTP requests:

MC-Api-Key: your_api_key

The API key is found from the API keys section under the user profile menu. If you don't see CloudMC API keys section, contact your system administrator as you may not have the permission to see that section. Your API key carries the same privileges as your CloudMC account, so be sure to keep it secret. If you think your API has been compromised, regenerate your API key from the API keys section.

Working with sub-organizations

If you don't know what a sub-organization is, you can safely skip this section.

When using the API in an organization other than your own, make sure to specify the org_id query parameter in your request. This looks like:

https://cloudmc_endpoint/api/v1/users&org_id=:org_id

HTTP verbs

The CloudMC API can be used by any tool that is fluent in HTTP. The appropriate HTTP method should be used depending on the desired action.

Verbs	Purpose
GET	Used to retrieve information about a resource.
POST	Used to create (or provision) a new resource or perform an operation on it.
PUT	Used to update a resource.
DELETE	Used to delete a resource.

Responses

Success response

# Example without tasks

{
  "data": [
    { "_comment" : "JSON representation of first object goes here" },
    { "_comment" : "JSON representation of second object goes here" }
  ]
}

# Example of compute API call with task

{
  "taskId": "c2c13744-8610-4012-800a-0907bea110a5",
  "taskStatus": "PENDING"
}

When an API request is successful, the response body will contain the data field with the result of the API call. If you're using the compute API, the data field might be empty since most of the operations are asynchronous. The response will contain the taskId and taskStatus fields so that you can retrieve the result of the operation you executed through the task API.

Attributes
data	The data field contains the object requested by the API caller.
taskId	The task id of an operation executed through the services API.
taskStatus	The status of a task of an operation executed the services API.

Error response

# Example of error response

{
  "errors": [
    {
      "code": 2012,
      "message": "Cannot stop an instance that isn't in the running state",
      "context": {
        "id": "4534cc36-bc46-48bc-ac5c-3ee4e42f0a44",
        "currentState": "Stopped",
        "expectedStates": [
          "Running"
        ],
        "type": "instances"
      }
    }
  ]
}

When an API request is unsuccessful, the response body will contain the errors field :

Attributes
errors	A list of errors objects that contain information about each error.

Each error has additional fields to describe it :

Attributes
code	The CloudMC error code.
message	A human readable explanation of the error code.
context	Additional information.

The HTTP status codes of error responses :

Status code	Reason
200	The request was successful.
204	The request was successful and the response body is empty.
400	Bad request -- Occurs when invalid parameters are provided or when quota limit is exceeded.
403	Forbidden -- Not authorized to perform this request.
404	Not Found -- Cannot locate the specified endpoint.
405	Method not allowed -- Cannot use that HTTP verb on the specified endpoint.
500	An unexpected error occurred.

Tasks

# Example of an asynchronus operation response

{
  "taskId": "b2f82e2a-123e-4f86-a4c7-dc9b850dd11e",
  "taskStatus": "PENDING"
}

Some operations take longer to execute, and to avoid blocking on the response until it is fully completed, these are treated in an asynchronous fashion. This means the API will return immediately, and provide you a taskId that is your reference to the ongoing background task. Using the tasks API, you can query the task's status to find if it has completed and obtain the result of the operation.

Retrieve a task

# Example of success response

{
  "taskId": "b2f82e2a-123e-4f86-a4c7-dc9b850dd11e",
  "taskStatus": "SUCCESS",
  "result": {
    "id": "8f064230-82a6-4f93-a17d-9cf9623b0cb5",
    "name": "morty"
  }
}

GET https://cloudmc_endpoint/api/v1/tasks/:id

A task has three different status: PENDING, FAILED and SUCCESS. On a successful completion of the task (i.e. it's in the SUCCESS state), the response will contain a result field which will contain the result of the operation. It is important to note that we don't persist our task, a task will only stay alive for 30 minutes (in general).

Administration

The following sections describe the various endpoints exposed by CloudMC to manage customer's configuration and interact with various core functionality of the system. Using these, you can automate various workflows without having to log into the portal, or simply integrate different aspects of CloudMC with your own toolchain.

Service connections

Service connections are the services that you can create resources for (e.g. compute, object storage). Service connections are scoped to Organizations. Thus, the relationship between a service connection and an organization can be either ownership (where the organization owns the connection) or assignation (where the connection is assigned to an organization but is owned by another) Environments are created for a specific service which allows you to create and manage resources within that service.

List service connections

GET /services/connections?organizationId=9571b279-abaf-4a37-9f39-85d1a915af7d

{
  "data":[{
    "id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
    "serviceCode": "compute-qc",
    "name": "Compute - Québec",
    "type": "CloudCA",
    "status": {  
      "lastUpdated": "2017-08-15T12:00:00.000Z",
      "reachable": true
    }
  }]
}

Attributes
id UUID	The id of the service connection.
serviceCode string	The service code of the service connection. It is used in the endpoint of the services API.
name string	The name of the service connection.
type string	The type of the service connection.
status Object	Status of the service connection. Tells you if the service is up. includes: lastUpdated, reachable.

Optional query parameters
organizationId string	The organization whose connections are to be retrieved. If this is not provided then the request defaults to the user's organization.

Retrieve a service connection

GET /services/connections/:id

{
  "data":[{
    "id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
    "serviceCode": "compute-qc",
    "name": "Compute - Québec",
    "type": "CloudCA",
    "status": {  
      "lastUpdated": "2017-08-15T12:00:00.000Z",
      "reachable": true
    }
  }]
}

Attributes
id UUID	The id of the service connection.
serviceCode string	The service code of the service connection. It is used in the endpoint of the services API.
name string	The name of the service connection.
type string	The type of the service connection.
status Object	Status of the service connection. Tells you if the service is up. includes: lastUpdated, reachable.

Retrieve connection parameters

GET /services/descriptors/:pluginType/parameters

# Retrieve service connection parameters

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/descriptors/gcp/parameters"

Request body example:

{
  "data": [
    {
      "field": "parentType",
      "label": "gcp.service_configuration.parameters.parent_type.label",
      "options": [
        {
          "value": "folder",
          "type": "option",
          "name": "gcp.service_configuration.parameters.parent_type.folder",
          "is18n": true
        },
        {
          "value": "organization",
          "type": "option",
          "name": "gcp.service_configuration.parameters.parent_type.organization",
          "is18n": true
        }
      ],
      "required": true,
      "type": "select"
    },
    {
      "field": "parentId",
      "label": "gcp.service_configuration.parameters.parent_id.label",
      "descriptionLabel": "gcp.service_configuration.parameters.parent_id.description",
      "required": true,
      "type": "text"
    },
    {
      "field": "jsonCredentials",
      "label": "gcp.service_configuration.parameters.json_credentials.label",
      "required": true,
      "type": "textarea"
    },
    {
      "field": "billingAccountId",
      "label": "gcp.service_configuration.parameters.billing_account.label",
      "descriptionLabel": "gcp.service_configuration.parameters.billing_account.description",
      "required": true,
      "type": "text"
    }
  ]
}

Attributes
data Array	An array of connection parameters, each with the following properties.
field string	The name of connection parameter.
type string	The type of the connection parameter. Possible values are text, textarea, select, checkbox.
options Array[select options]	A list of possible options for parameters of type = select
required boolean	An indication as to whether or not this parameter is a required one when creating a service connection.

This call returns a list of parameters that must be provided (when creating a new ServiceConnection) for CloudMc to be able to successfully connect to service. While, the response includes a variety of information, the field attribute of each paramter object returned is the parameter identifier. This is used together with some value to provide the connection parameters when creating a new ServiceConnection.

Create service connection

POST /services/connections

# Create a service connection

curl -X POST "https://cloudmc_endpoint/api/v1/services/connections" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
   "name":"GCP-AmericasRegion",
     "type":"gcp",
     "serviceCode":"gcp-americas",
   "organization": {
         "id": "9571b279-abaf-4a37-9f39-85d1a915af7d"
     },
   "parameters":[
      {
         "parameter":"parentType",
         "value":"folder"
      },
      {
         "parameter":"parentId",
         "value":"9123843023"
      },
      {
         "parameter":"jsonCredentials",
         "value":"<GCP-SERVICE-ACCOUNT-CREDENTIALS>"
      },
      {
         "parameter":"billingAccountId",
         "value":"141F7D-FDK3D0-F99HW2"
      },
      {
         "parameter":"billingSubAccountsEnabled",
         "value":""
      },
      {
         "parameter":"billingDatasetName",
         "value":"cmc_usage"
      }
   ]
}

Create a new service connection in a specific organization. You will need the Reseller connections permission to execute this operation.

Required
name string	The name of the new service connection.
type string	The type of new service connection. (e.g. gcp, azure, aws, cloudca, swift, etc.)
serviceCode string	A globally unique code that identifies this service connection.
organization Organization	The organization that the service connection should be created in. required attributes of the organization: id
parameters Array[connection parameters]	An array of connection parameters specific to this connection type along with their values. This array should contain all required parameters from the list returned from the retrieve connection parameters API. required attributes per parameter: parameter, value.

Test new service connection

POST /services/connections/test

# Test a new service connection

curl -X POST "https://cloudmc_endpoint/api/v1/services/connections/test" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

# requires the same request body 
# as outlined in the 'Create service connection' section

Test a new service connection before creating it. The request body is the same as that which is used when creating a new service connection.

Test existing service connection

POST /services/connections/:id/test

# Test a new service connection

curl -X POST "https://cloudmc_endpoint/api/v1/services/connections/9571b279-abaf-4a37-9f39-85d1a915af7d/test" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json"

Test an existing service connection. This request does not require a body. The connection id is passed as a path parameter in the request.

Retrieve connection policy descriptors

GET /services/connections/:id/policies/descriptors

Query Parameters
section string	The name of the policy section to load. Only the policy section matching the section name provided will return all required FormElements and the connection entity.

# Retrieve connection policy descriptors
curl "https://cloudmc_endpoint/api/v1/services/connections/03bc22bd-adc4-46b8-988d-afddc24c0cb5/policies/descriptors?section=trials" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data":[{
    "name": "general",
    "label": "general",
    "optional": false,
  },{
    "name": "trials",
    "formElements": [{
      "label": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.label",
      "descriptionLabel": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.description",
      "interpolation": {},
      "options": [{
        "value": "isolatedNetwork",
        "type": "option",
        "name": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.options.isolated_network",
        "is18n": true
      }, {
        "value": "singleNetwork",
        "type": "option",
        "name": "cloudstack.service_configuration.policies.trials.network_config_for_trial_env.options.single_subnet_vpc",
        "is18n": true
      }],
      "disabled": false,
      "required": true,
      "field": "trials:network_config_for_trial_envs",
      "reloadOnChange": false,
      "sectionsToReload": [],
      "type": "select"
    }],
    "entity": {
      "id": "7486dfbf-740d-49b1-ba68-6e4b0070ebbb",
      "name": "Google Cloud Connection",
      "policies": {
        "version": "1.0",
        "cacheEnabled": "false",
        "regions": "us-east,eu-west"
      }
    }
  }]
}

Attributes
name string	The name of the policy section.
label string	The label key for the policy section name.
formElements Array	The FormElements returned by the policy section. Form elements are only returned for a given section if the query param section matches the name of a policy section.
optional boolean	Specifies if the policy section is required or not.
entity Object	The service connection entity which includes a string to string map of the ServiceConnectionPolicy::name to ServiceConnectionPolicy::value.

Update connection policies

PUT /services/connections/:id/policies

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "[{"name": "serviceVersion", "value": "1.1"}, {"name": "cacheEnabled", "value": "true"}]" \
   "https://cloudmc_endpoint/api/v1/services/connections/03bc22bd-adc4-46b8-988d-afddc24c0cb5/policies"

The above command returns a JSON structured like this:

{
  "data":[
    {
      "id": "003c32af-e4e0-440c-871e-f20a81e6c0b7",
      "name": "serviceVersion",
      "value": "1.1"
    },
    {
      "id":"a31f100a-f7c8-43d5-b64d-ee2db466f37d",
      "name": "cacheEnabled",
      "value": "true"
    },
    {
      "id": "c681774a-a96c-4dff-a2a6-2e9651459de7",
      "name": "regions",
      "value":"us-east,eu-west"
    }]
}

Attributes
name string	The name of the policy.
value string	The policy value.

List organizations assigned to a service connection

GET /services/connections/:id/assigned_organizations?organizationId=:orgId

{
  "data": [
    {
      "id": "679fe078-a67a-4383-ab4e-51f5ef3a9287",
      "name": "MyOrg",
      "entryPoint": "my-org",
      "state": "PROVISIONED",
      "quota": {
        "id": "90c3e469-71c7-4231-b27b-31dcf3a820ad",
        "name": "Unlimited"
      }
    },
    {
      "id": "9571b279-abaf-4a37-9f39-85d1a915af7d",
      "name": "Sysco Labs",
      "entryPoint": "syscolab",
      "state": "PROVISIONED",
      "quota": {
        "id": "66a773e8-a7e9-498b-a01d-68c8f9df2fd4",
        "name": "trial"
      }
    },
    {
      "id": "d84125c6-1417-4aa3-8293-a5ddde2bfeac",
      "name": "Symcentric",
      "entryPoint": "symcentric",
      "state": "PROVISIONED",
      "quota": {
        "id": "66a773e8-a7e9-498b-a01d-68c8f9df2fd4",
        "name": "trial"
      }
    },
  ]
}

Returns a list of organizations to which the service connection is assigned. Only organizations that the caller has access to will be returned. Read description of the organizationId query parameter below for more details about the returned list.

Attributes
id UUID	The id of the organization.
name string	The name of the organization.
entryPoint string	The entry point of the organization. Also refered to as the organization code.
state string	The provisioning state of the organization on the backend service. States: PENDING, PROVISIONING, PROVISIONED, PENDING_PURGE, PURGING, PURGED.
quota Object	The quota assigned to the organization (may be null depending on if the connection supports quotas or not). includes: id, name

Optional query parameters
organizationId string	The organization from whose scope the request is being made. Based on this the returned list may vary. Organizations that are above this organization (represented by the id) in the organization tree hierarchy will be filtered from the returned list even if they have the connection assigned to them. If this is not provided then the request defaults to the user's organization.

Organizations

Organizations are the largest logical grouping of users, environments and resources available in CloudMC. Each organization is isolated from other organizations. It has its own subdomain ([entryPoint].CloudMC) and is protected by its own customizable system roles. An administrator that must manage its sub-organizations environments or provisioned resources can do so by having the Access other levels permission. Additionally, provisioned resource usage is metered at the organization level facilitating cost tracking.

List organizations

GET /organizations

Retrieves a list of organizations visible to the caller. In most cases, only the caller's organization will be returned. However if the caller's organization has sub-organizations, and the caller has the Access other levels permission, the sub-organizations will be returned as well.

# Retrieve visible organizations
curl "https://cloudmc_endpoint/api/v1/organizations" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
   "data": [
      {
         "id": "03bc22bd-adc4-46b8-988d-afddc24c0cb5",
         "name": "Umbrella Corporation",
         "entryPoint": "umbrella",
         "billableStartDate": "2017-08-15T12:00:00.000Z",
         "billingDay": 5,
         "isBillable": true,
         "billingMode": "CREDIT_CARD",
         "isReseller": false,
         "tags": [
            {
               "system": true,
               "name": "billable",
               "id": "5a84485f-7eed-11ec-b819-0242ac120002"
            },
            {
               "system": false,
               "name": "organizationTagOne",
               "id": "fc2a164f-3871-4eed-9591-d3ceb838550b"
            },
            {
               "system": false,
               "name": "organizationTagTwo",
               "id": "12d6d802-ca56-4c22-9c9d-e76ee0b1e97c"
            }
         ],
         "deleted": false,
         "parent": {
            "id": "8e3393ce-ee63-4f32-9e0f-7b0200fa655a",
            "name": "Capcom"
         },
         "environments": [
            {
               "id": "9df14056-51e2-4000-ab14-beeaa488500d",
               "deleted": false
            }
         ],
         "roles": [
            {
               "id": "cdaaa9d0-304e-4063-b1ab-de31905bdab8",
               "deleted": false
            }
         ],
         "serviceConnections":[
            {
               "id":"11607a49-9691-40fe-8022-2e148bc0d720",
               "serviceCode":"compute-qc"
            }
         ],
         "users": [
            {
               "id":"0c3ffcce-a98d-4159-b6fc-04edd34e89b7",
               "userName":"wbirkin",
               "deleted": false
            }
         ]
      }
   ]
}

Optional Query Parameters
include_deleted boolean	Whether or not to include deleted organizations and resources in the response.

Attributes
id UUID	The id of the organization.
name string	The name of the organization.
entryPoint string	The entry point of the organization is the subdomain of the organization in the CloudMC URL : [entryPoint].CloudMC.
billableStartDate string	The billable start date in ISO 8601 of the organization.
billingDay int	The billing day of the organization. Default value is 1.
isBillable boolean	If the organization is billable this values is true, false otherwise.
billingMode enum	The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL".
tags Array[object]	Tags associated to the organization. includes: idUUID, namestring, systemboolean
parent Organization	If the organization is a sub-organization, it will have its parent organization. includes:id,name.
environments Array[Environment]	The environments belonging to the organization. includes: id
roles Array[Role]	The system and environments roles belonging to the organization. includes: id
serviceConnections Array[ServiceConnection]	The services for which the organization is allowed to provision resources. includes: id,serviceCode
resourceCommitments Array[ResourceCommitment]	The resource commitments applied on the organization.
users Array[User]	The users of the organization. includes: id
notes string	Organization notes.
isDbAuthentication boolean	Whether or not the organization supports database authentication.
isLdapAuthentication boolean	Whether or not LDAP authentication is enabled on this organization.
isTrial boolean	Whether or not this is a trial organization.
isReseller boolean	Whether or not this organization is a reseller or not.
customDomain VerifiedDomain	The custom domain for the organization.

Retrieve an organization

GET /organizations/:id

Retrieve an organization's details.

# Retrieve an organization
curl "https://cloudmc_endpoint/api/v1/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
   "data": {
      "id": "03bc22bd-adc4-46b8-988d-afddc24c0cb5",
      "name": "Nintendo US",
      "entryPoint": "nintendo-us",
      "billableStartDate": "2017-08-15T12:00:00.000Z",
      "billingDay": 5,
      "isBillable": true,
      "billingMode": "CREDIT_CARD",
      "isReseller": false,
      "tags": [
         {
            "system": true,
            "name": "billable",
            "id": "5a84485f-7eed-11ec-b819-0242ac120002"
         },
         {
            "system": false,
            "name": "organizationTagOne",
            "id": "fc2a164f-3871-4eed-9591-d3ceb838550b"
         },
         {
            "system": false,
            "name": "organizationTagTwo",
            "id": "12d6d802-ca56-4c22-9c9d-e76ee0b1e97c"
         }
      ],
      "parent": {
         "id": "8e3393ce-ee63-4f32-9e0f-7b0200fa655a",
         "name": "Nintendo"
      },
      "environments": [
         {
           "id": "9df14056-51e2-4000-ab14-beeaa488500d"
         }
      ],
      "roles": [
         {
           "id": "cdaaa9d0-304e-4063-b1ab-de31905bdab8"
         }
      ],
      "serviceConnections": [
         {
            "id":"11607a49-9691-40fe-8022-2e148bc0d720",
            "serviceCode":"compute-qc"
         }
      ],
      "users": [
         {
            "id":"0c3ffcce-a98d-4159-b6fc-04edd34e89b7",
            "userName":"reggie"
         }
      ]
  }
}

Attributes
id UUID	The id of the organization.
name string	The name of the organization.
entryPoint string	The entry point of the organization is the subdomain of the organization in the CloudMC URL : [entryPoint].CloudMC.
billableStartDate string	The billable start date in ISO 8601 of the organization.
billingDay int	The billing day of the organization. Default value is 1.
isBillable boolean	If the organization is billable this values is true, false otherwise.
billingMode enum	The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL".
tags Array[object]	Tags associated to the organization. includes: idUUID, namestring, systemboolean
parent Organization	If the organization is a sub-organization, it will have its parent organization. includes:id,name.
environments Array[Environment]	The environments belonging to the organization. includes: id
roles Array[Role]	The system and environments roles belonging to the organization. includes: id
serviceConnections Array[ServiceConnection]	The services for which the organization is allowed to provision resources. includes: id,serviceCode
resourceCommitments Array[ResourceCommitment]	The resource commitments applied on the organization.
users Array[User]	The users of the organization. includes: id
notes string	Organization notes.
isDbAuthentication boolean	Whether or not the organization supports database authentication.
isLdapAuthentication boolean	Whether or not LDAP authentication is enabled on this organization.
isTrial boolean	Whether or not this is a trial organization.
isReseller boolean	Whether or not this organization is a reseller or not.
customDomain VerifiedDomain	The custom domain for the organization.

Create organization

POST /organizations

Creates a new organization as a sub-organization of the caller's organization, or a sub-organization of the specified parent. The caller requires the Organizations create permission.

# Create an organization
curl -X POST "https://cloudmc_endpoint/api/v1/organizations" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
   "entryPoint":"umbrella",
   "name":"Umbrella Corp",
   "serviceConnections":[
      {
         "id":"9acb3b76-d5d0-420c-b075-ef320b7e5a3e"
      }
   ],
   "parent" : {
      "id":"bc0ceecf-feb5-412c-ab6e-a8df8eb7fbbd"
   }
}

Required
name string	The name of the organization. (Add info about restrictions)
entryPoint string	The entry point of the organization is the subdomain of the organization in the CloudMC URL : [entryPoint].CloudMC.

Optional
serviceConnections Array[ServiceConnection]	A list of service connections for which the organization may provision resources. required :id
parent Organization	The organization that will be the parent of the new organization. By default, it will default to the caller's organization. required :id
billingDay int	The billing day of the organization. Must be between 1 and 28 (inclusive), the default value is 1.
billingMode enum	The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL".
tags Array[object]	Tags associated to the organization. Tags provided in the request cannot be system tags. required : id or name

The responses' data field contains the created organization with its id.

Update organization

PUT /organizations/:id

Update an organization. Its parent organization cannot be changed. It can be assigned service connections.

# Update an organization
curl -X PUT "https://cloudmc_endpoint/api/v1/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
   "entryPoint":"umbrella",
   "name":"Umbrella Corp",
   "serviceConnections":[
      {
         "id":"9acb3b76-d5d0-420c-b075-ef320b7e5a3e"
      }
   ]
}

Optional
name string	The name of the organization. (Add info about restrictions)
entryPoint string	The entry point of the organization is the subdomain of the organization in the CloudMC URL : [entryPoint].CloudMC.
serviceConnections Array[ServiceConnection]	A list of service connections for which the organization may provision resources. The caller must have access to all connections that are provided. Read below (after the request parameter list) for more details. required attributes of the service connection: id
tags Array[object]	Tags associated to the organization. Tags provided in the request cannot be system tags. Must have the Reseller: Organizations metadata: Manage permission. User cannot modify tags of their own (non-root) organization. required : id or name
resourceCommitments Array[ResourceCommitment]	The resource commitments applied on the organization.
users Array[User]	The users of the organization. required attributes of the organization : id
notes string	Organization notes. Must have the Organization metadata: Manage permission.
isDbAuthentication boolean	Whether or not the organization supports database authentication.
isLdapAuthentication boolean	Whether or not LDAP authentication is enabled on this organization.
customDomain VerifiedDomain	An object describing a verified domain. Must have the Organization: Manage reseller features permission. required : id
billingDay int	The billing day of the organization. Must be between 1 and 28 (inclusive), the default value is 1.
billingMode enum	The billing mode of the organization. It could be either "MANUAL" or "CREDIT_CARD". Default value is "MANUAL".

The responses' data field contains the updated organization.
NB : At this time the API only enables adding access to Service connections but not revoking it. A Service connection can be assigned to an organization only if:

• The organization owns the service connection (i.e. the organizationId of the service connection is this organization's id)
• If the organization is a sub-organization in some organization hierachy, then the service connection must be either owned by or assigned to its immediate parent organization

Delete organization

DELETE /organizations/:id

Delete an organization. The caller may not delete his own organization. Also, an organization may not be deleted if it has sub-organizations.

# Delete an organization
curl -X DELETE "https://cloudmc_endpoint/api/v1/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key"

Returns an HTTP status code 204, with an empty response body.

Get verified domains

GET /organizations/:organization_id/verified_domains

Get a list of all verified domains on the specified organization.

# Retrieve all verified domains
curl "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/verified_domains" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "lastCheckedDate": "2020-07-31T19:14:36Z",
      "createdDate": "2020-07-31T19:12:55Z",
      "domain": "aGoodFakeDomain.com",
      "organization": {
        "name": "my organization",
        "id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
        "entryPoint": "myOrg"
      },
      "id": "22d30872-8e90-43b5-b1ba-636bead42e34",
      "verificationCode": "cmc-verification=81405f20-f96e-4964-b8bb-fb97c802ca5c",
      "status": "VERIFIED"
    },
    {
      "lastCheckedDate": "2020-08-03T15:24:35Z",
      "createdDate": "2020-08-03T14:41:20Z",
      "domain": "anotherFakeDomain.com",
      "organization": {
        "name": "my organization",
        "id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
        "entryPoint": "myOrg"
      },
      "id": "5752811e-08cf-4105-91ca-bac80efe3d23",
      "verificationCode": "cmc-verification=a571fb45-1dc6-4569-adf2-9e166861499f",
      "status": "PENDING"
    }
  ]
}

Attributes
lastCheckedDate string	The last date that the domain's DNS was checked for the TXT record with the verification code. In ISO 8601.
domain string	The domain associated with the organization.
organization Organization	The organization to which the verified domain belongs. includes:id,name, entryPoint.
id UUID	The id of the verified domain.
verificationCode string	The verification code for the domain. This is the value that should be added to the domain's DNS registration as a new TXT record. CloudMC will check on a recurring schedule if the TXT record has been added to the domain, and update the status to VERIFIED once found.
status string	The status of the domain ownership proof. Possible values are : VERIFIED, PENDING, ERROR.

Create verified domain

POST /organizations/:organization_id/verified_domains

Creates a new verified domain in the specified organization.

# Create a verified domain
curl -X POST "https://cloudmc_endpoint/api/v1/organizations87895f43-51c1-43cc-b987-7e301bf5b86a/verified_domains" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
   "domain":"www.umbrellaCorp.com"
}

Required
domain string	The domain associated with the organization.

The responses' data field contains the created verified domain with its id, as well as with the verificationCode. A TXT record will need to be added to the domain's DNS registration with the verification code as its value.

Delete verified domain

DELETE /organizations/:organization_id/verified_domains/:id

Delete a specified domain on the organization.

# Delete a verified domain
curl -X DELETE "https://cloudmc_endpoint/api/v1/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/verified_domains/22d30872-8e90-43b5-b1ba-636bead42e34" \
   -H "MC-Api-Key: your_api_key"

Returns an HTTP status code 200, with an empty response body.

Get security settings

GET /organizations/organization_id/security_settings

Retrieve the security settings for the organization.

# Retrieve the organization's security settings
curl "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/security_settings" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "defaultRole": {
      "name": "guest",
      "id": "6e022506-ab89-4676-859d-06d370b67417"
    },
    "organization": {
      "name": "my organization",
      "id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
      "entryPoint": "myOrg"
    },
    "autoCreationEnabled": true,
    "verifiedDomains": [
       {
        "lastCheckedDate": "2020-08-03T17:19:36Z",
        "createdDate": "2020-08-03T16:14:00Z",
        "domain": "newDomainName.com",
        "organization": {
          "lineage": "87895f43-51c1-43cc-b987-7e301bf5b86a",
          "notes": "",
          "hashAlgorithmName": "SHA-512",
          "hashIterations": 100,
          "isTrial": false,
          "creationDate": "2020-04-30T21:25:49.000Z",
          "version": 2,
          "isLdapAuthentication": false,
          "isBillable": false,
          "isDbAuthentication": true,
          "deleted": false,
          "ldap": {
            "id": "063ec8ee-8a55-4374-9c8c-57a10f11cf1b"
          },
          "name": "my organization",
          "id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
          "entryPoint": "myOrg"
        },
        "id": "29d66b1d-669a-439b-883a-d7c1e36e1ca6",
        "verificationCode": "cmc-verification=8c8f5473-9306-4e16-a820-a747482e85e5",
        "status": "VERIFIED"
      }
    ],
    "passwordPolicy": {
      "constraints": [
        {
          "name": "min_password_length",
          "value": 8,
          "isMandatory": false
        },
        {
          "name": "min_lowercase_letters",
          "value": 1,
          "isMandatory": true
        },
        {
          "name": "min_uppercase_letters",
          "value": 1,
          "isMandatory": true
        },
        {
          "name": "min_numbers",
          "value": 1,
          "isMandatory": true
        },
        {
          "name": "min_special_characters",
          "value": 1,
          "isMandatory": true
        }
      ]
    }
  }
}

Attributes
defaultRole object	The role that will be assigned to new users logging into the organization with an email domain matching that of the organization's security settings.
defaultRole.name string	The name of the default role.
defaultRole.id UUID	The id of the default role.
organization Organization	The organization to which the verified domain belongs. includes:id,name, entryPoint.
autoCreationEnabled boolean	A boolean specifying whether to enable automatic end-user account creation upon successful OIDC login.
verifiedDomains Array[verified domains]	A list of verified domains (with VERIFIED status) for which successful matching OIDC logins will create new users.
passwordPolicy object	The password policy assigned to the organization.
passwordPolicy.constraints Array[Object]	List of password policy constraints.
passwordPolicy.constraints.name string	A string that represents the constraint name.
passwordPolicy.constraints.value int	An integer that represents the minimum value for the constraint.
passwordPolicy.constraints.isMandatory boolean	A boolean flag to indicate if the constraint is mandatory or not.

Update security settings

PUT /organizations/:organization_id/security_settings

# Update an organization's security settings
curl -X PUT "https://cloudmc_endpoint/api/v1/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/security_settings" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
   "autoCreationEnabled": true,
   "verifiedDomains": [ 
        { 
             "id": "29d66b1d-669a-439b-883a-d7c1e36e1ca6"
        }
    ],
    "defaultRole": {
      "name": "guest",
      "id": "6e022506-ab89-4676-859d-06d370b67417" 
    },
   "passwordPolicy": {
      "constraints": [
         {
               "name": "min_password_length",
               "value": 8,
               "isMandatory": false
         },
         {
               "name": "min_lowercase_letters",
               "value": 1,
               "isMandatory": true
         },
         {
               "name": "min_uppercase_letters",
               "value": 1,
               "isMandatory": true
         },
         {
               "name": "min_numbers",
               "value": 1,
               "isMandatory": true
         },
         {
               "name": "min_special_characters",
               "value": 1,
               "isMandatory": true
         }
      ]
   }
}

Create a new or update an existing security settings for an organization.

Required
defaultRole object	The role that will be assigned to new users logging into the organization with an email domain matching that of the organization's security settings.
defaultRole.name string	The name of the default role.
defaultRole.id UUID	The id of the default role.

Optional
autoCreationEnabled boolean	A boolean specifying whether to enable automatic end-user account creation upon successful OIDC login.
verifiedDomains Array[verified domains]	A list of objects containing the ids of verified domains (with VERIFIED status) for which successful matching OIDC logins will create new users.
passwordPolicy object	The password policy that will be assigned to the organization.
passwordPolicy.constraints Array[Object]	List of password policy constraints objects with the following fields.
passwordPolicy.constraints.name string	A string that represents the constraint name.
passwordPolicy.constraints.value int	An integer that represents the minimum value for the constraint.
passwordPolicy.constraints.isMandatory boolean	A boolean flag to indicate if the constraint is mandatory or not.

Returns an HTTP status code 200, with an empty response body.

• If defaultRole is not passed in the request:
  • The system will assign Guestas a default role to the organization.
• If passwordPolicy is passed in the request:
  • The system will create a new or update the existing password policy for the organization.
• If autoCreationEnabled and/or verifiedDomains is passed in the request:
  • The system will create a new or update the existing security settings for the organization.

Get password policy

GET /organizations/organization_id/password_policy

Retrieve the password policy for the organization.

# Retrieve the organization's own or inherited password policy.
curl "https://cloudmc_endpoint/api/v1/organizations/e8d95716-26a9-4054-833e-81cd3a5155cd/password_policy" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "name": "min_password_length",
            "value": 8,
            "isMandatory": true
        },
        {
            "name": "min_lowercase_letters",
            "value": 1,
            "isMandatory": true
        },
        {
            "name": "min_uppercase_letters",
            "value": 1,
            "isMandatory": true
        },
        {
            "name": "min_numbers",
            "value": 1,
            "isMandatory": true
        },
        {
            "name": "min_special_characters",
            "value": 1,
            "isMandatory": true
        }
    ]
}

Attributes
Array[Object]	A list of password policy constraint objects with the following fields.
name string	The name of the constraint.
value int	The minimum value for the constraint.
isMandatory boolean	Flag to indicate if the constraint is mandatory or not.

Delete password policy

DELETE /organizations/:id/password_policy

Delete a password policy for an organization. Root reseller organization will not be able to delete its password policy. A reseller sub-organization can delete its password policy.

# Delete an organization
curl -X DELETE "https://cloudmc_endpoint/api/v1/organizations/e8d95716-26a9-4054-833e-81cd3a5155cd/password_policy" \
   -H "MC-Api-Key: your_api_key"

Returns an HTTP status code 204, with an empty response body.

Get manageable connections of an organization

GET /organizations/:id/manageable_connections

Get a list of Service connections that can be managed by the current user on the given organization.

# Update an organization
curl -X GET "https://cloudmc_endpoint/api/v1/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/manageable_connections" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

[
  {
    "id": "2f7b4d49-b426-424f-b272-396b66947bb1",
    "name": "Microsoft Azure",
    "type": "azure",
    "serviceCode": "azure-dev",
    "status": {
      "id": "97b3f5fa-1bda-4dae-b716-8039d9b89a56",
      "serviceConnection": null,
      "reachable": true,
      "lastUpdated": null,
      "message": null,
      "version": null
    },
    "quotas": []
  },
  {
    "id": "b1dc9202-4e1a-4180-9ed6-28025b5aacdd",
    "name": "Objects Lab",
    "type": "swiftstack",
    "serviceCode": "objects-lab",
    "status": {
      "id": "74a78d2b-c0da-475e-9bb7-218adc745d81",
      "serviceConnection": null,
      "reachable": true,
      "lastUpdated": null,
      "message": null,
      "version": null
    },
    "quotas": [
      { ... },
      { ... },
    ]
  }
]

Attributes
id string	The id of the service connection.
name string	The name of the service connection.
type string	The type of the service connection. (e.g. gcp, azure, aws, cloudca, swift, etc.)
serviceCode string	The globally unique serviceCode that identifies the service connection.
status Object	The status object describing the status of connectivity to this service from CloudMc.
quotas Array[Quotas]	A list of quotas that can be associated to the service connnection.

The user should have Connections reseller permission on the organization. This list includes the following types of Service connections:

• If the API user is from this organization:
  • Service connections owned by and assigned to this organization
• If the API user is from this organization's immediate parent organization:
  • Service connections assigned to this organization
  • Service connections owned by and assigned to this organization's immediate parent organization (i.e. the user's organization)
• If the API user is from any organization between this organization's immediate parent organization and the root organization:
  • Service connections assigned to this organization
  • Service connections owned by the user's organization and is assigned to this organization's immediate parent organization
  • Service connections assigned to the user's organization and is assigned to this organization's immediate parent organization

Mark organization as reseller

POST /organizations/:organization_id/mark_reseller

# Mark an organization as reseller
curl -X POST "https://cloudmc_endpoint/api/v1/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5/mark_reseller" \
   -H "MC-Api-Key: your_api_key" \

Mark the organization as a reseller. Returns an HTTP status code 200, with an empty response body.

Get identity providers

GET /organizations/:organization_id/identity_providers

Retrieve the identity providers for the organization.

# Retrieve the organization's identity providers
curl "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/identity_providers" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "32a5640c-b366-44b1-882a-ee2e1951c592",
      "organization": {
        "name": "my organization",
        "id": "87895f43-51c1-43cc-b987-7e301bf5b86a",
        "entryPoint": "myOrg"
      },
      "type": "OIDC",
      "css": "",
      "provider": "GOOGLE",
      "displayName": "Google",
      "logo": "/static/img/google_signin.svg",
      "rank": 1
    }
  ]
}

Attributes
id UUID	The id of the identity provider.
organization Organization	The organization to which the verified domain belongs. includes:id,name, entryPoint.
type string	The type of authentication protocol. Possible values: OIDC, SAML.
css string	Custom css for the login button of the identity provider.
provider string	The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider.
displayName string	The display name of the identity provider that will appear on the login screen.
logo string	A base64 encoded data URL or URL to an image for the logo to display on the login screen.
rank int	If provided, this integer sorts identity providers on the Login page in ascending order.

Get billing information

GET /organizations/:organization_id/billing_info

Retrieve the billing information for an organization.

# Retrieve the organization's billing information
curl "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_info" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "23910576-d29f-4c14-b663-31d728ff49a5",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "billingProvider": {
      "id": "f26e66a4-755c-4867-b565-ad68aa515237"
    },
    "cardType": "Mastercard",
    "cardMaskedNumber": "************1234",
    "cardName": "John Doe",
    "cardExp": "0124",
    "billingAddressLineOne": "555 SomeStree",
    "billingAddressLineTwo": "App #2",
    "billingAddressCity": "SomeCity",
    "billingAddressProvince": "NY",
    "billingAddressPostalCode": "555555",
    "billingAddressCountry": "US",
    "customAttribute" : {
      "uid": "774B145528524D7C65590CE77B933135",
      "customerRefNumber": "208523664"
    }
  }
}

Attributes
id UUID	The id of the billing information.
organization Organization	The organization to which belongs the billing information.
billingProvider BillingProvier	The billing provider associated to the credit card.
cardType string	The credit card type.
cardMaskedNumber string	The credit card masked number.
cardName string	The name on the credit card
cardExp string	The credit card expiration ('mmyy' format)
billingAddressLineOne string	The address line 1 of the billing address.
billingAddressLineTwo string	The address line 2 of the billing address.
billingAddressCity string	The city of the billing address.
billingAddressProvince string	The province or state code (2 letters) of the billing address.
billingAddressPostalCode string	The postal/zip code of the billing address.
billingAddressCountry string	The country code (ISO 2 or 3 letter code) of the billing address
billingAddressCountry string	The country code (ISO 2 or 3 letter code) of the billing address
customAttribute Object	The custom attributes associated to the billing provider

Chase attributes
customAttribute.uid string	Chase registration id
customAttribute.customerRefNum string	Chase customer reference number/profile id

Clear credit card information

DELETE /organizations/:organization_id/billing_info

Delete the billing information for an organization. Only accessible to system operator.

Returns an HTTP status code 200, with an empty response body.

# Retrieve the organization's billing information
curl -X DELETE "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_info" \
   -H "MC-Api-Key: your_api_key"

Set billable organization information

PUT /organizations/:organization_id/billable

Set the organization to billable and update the billable organization information. If the organization's assigned pricing package is changed, this API will reprocess usage starting from the current in progres billing cycle. Any previously drafted invoices will be generated and reports will reflect the pricing configuration of the newly selected pricing package.

# Update billable organization info
curl -X PUT "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billable" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
   "id": "39f6260d-f0ca-4be9-93c4-46405d471c04",
   "billableStart": "2015-01-18",
    "pricingPackage": {
        "id": "58bad1de-1f87-422b-b44f-27ed58889272"
    }
}

Required
id UUID	The id of the udpated billable organization information.
billableStart string	The date the organization became billable, in YYYY-MM-DD format.
pricingPackage.id UUID	The id of the pricing package applied on the organization.

Optional
billableEnd string	The date the organization stops being billable, in YYYY-MM-DD format.

List applicable pricing packages to an organization

GET /organizations/:organization_id/pricing_packages

Retrieves a list of applicable pricing packages to an organization.

# Retrieve visible organizations
curl "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/pricing_packages" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "offerType": "30-day-trial",
      "pricingDefinition": {
        "id": "c9a396f1-690a-4201-a3bf-b1da37221acc"
      },
      "endDate": "2022-09-14T00:00:00Z",
      "organization": {
        "id": "de6cf332-14b2-4da8-8522-3dfe12fcd0da"
      },
      "name": {
        "en": "Applied Pricing",
        "fr": "Applied Pricing"
      },
      "id": "92041aa8-7784-45b0-aa85-76376ede784d",
      "creationDate": "2021-09-13T15:18:38.000Z",
      "startDate": "2021-09-22T20:09:32.084Z"
    }
  ]
}

Attributes
id UUID	The UUID of the pricing package.
offerType string	The offer type of the pricing package.
pricingDefinition Object	The pricing definition associated with the pricing package.
pricingDefinition.id UUID	The UUID of the pricing.
organization Object	The object representing the organization owning the pricing package.
organization.id UUID	The UUID of the organization.
startDate date	The start date of the pricing package.
endDate date	The end date of the pricing package. If it is not present, there is no end date defined.
creationDate Object	The date the pricing package was created.
name Object	A map of language keys to the name of the pricing package in the specified language.

List billing emails

GET /organizations/:organization_id/billing_emails

Retrieves a list of billing emails configured on the org. These emails will also receive billing related emails along with users that have the Admin:Billing role.

# Retrieve billing emails
curl "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_emails" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "billingEmails": {
      "example@email.com": "John",
      "billing@company.com": "Billing team"
    }
  }
}

Attributes
billingEmails map	A map of billing emails and names associated with them.

Update billing emails

PUT /organizations/:organization_id/billing_emails

Update the list of billing emails configured on the org. These emails will also receive billing related emails along with users that have the Admin:Billing role.

# Update billing emails
curl "https://cloudmc_endpoint/api/v1/organizations/87895f43-51c1-43cc-b987-7e301bf5b86a/billing_emails" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
   "billingEmails": {
      "example@email.com": "John",
      "billing@company.com": "Billing team"
   }
}

Required
billingEmails map	A map of billing emails and names associated with them. There is a maximum of three emails that can be configured. Each entry must have a valid email specified along with a name.

Get a billing cycle for an org

GET /organizations/:organization_id/billing_cycles/:billing_cycle_id

Retrieves a billing cycle for the organization.

# Retrieve billing cycle
curl "https://cloudmc_endpoint/api/v1/organizations/c01e2bd4-50c4-4ef4-b756-f728823309a4/billing_cycles/8259182d-5234-4a78-adf6-7edc11db2e3b" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "pricingPackages": [
      {
        "endDate": "2021-12-01",
        "packageId": "508a1f5f-2504-41ac-b48f-b87e757840a4",
        "name": {
          "en": "Cox Pricing Package"
        },
        "startDate": "2021-11-01"
      }
    ],
    "deferred": false,
    "invoices": [],
    "discounts": [
      {
        "endDate": "2021-11-11",
        "name": {
          "en": "Credit 01"
        },
        "discountId": "e6ada5f6-9806-466c-8522-314da152a8e7",
        "type": "CREDIT",
        "startDate": "2021-11-01",
        "remaining": {
          "discountedProducts": {},
          "discountedCategories": {},
          "packageDiscount": 10.0,
          "labels": {}
        }
      },
    ],
    "endDate": "2021-12-01",
    "currency": "USD",
    "id": "8259182d-5234-4a78-adf6-7edc11db2e3b",
    "state": "IN_PROGRESS",
    "startDate": "2021-11-01"
  }
}

Attributes
id UUID	The id of the billing cycle.
startDate string	The start date in ISO 8601 of the billing cyle.
endDate string	The end date in ISO 8601 of the billing cyle.
currency string	The currency associated to the organization.
deferred boolean	Indicates whether the billing cycle is deferred or not.
invoices Array[UUID]	Array of UUIDs of the invoices associated with the billing cycle.
pricingPackages Array[Object]	List of pricing packages associated with the billing cycle.
pricingPackages.endDate string	The end date in ISO 8601 of when the pricing package was applied to the billing cycle.
pricingPackages.startDate string	The start date in ISO 8601 of the pricing package associated with the billing cycle.
pricingPackages.name Map[String, String]	The name translations of the pricing package.
discounts Array[Object]	List of discounts applied during the billing cycle.
discounts.endDate date	The end date of the discount.
discounts.startDate date	The start date of the discount.
discounts.name Map[String, String]	The name translations of the discount.
discounts.type enum	The type of the discount. It could be either "PERCENTAGE" or "CREDIT".
discounts.remaining Object	Tracking of the credits remaining and used for the billing cycle.
discounts.discountId UUID	The UUID of the discount.
state enum	The state of the billing cycle. It could be "NONE", "WAITING_INVOICE", "WAITING_PAYMENT", "PAID", "IN_PROGRESS", or "FUTURE".

Users

A user account allows users to authenticate to an organization and to have access to the resources in it. You can restrict user access to the system and environments by assigning them specific roles. Additionally, every user is given an API key which is needed to use our APIs. All operations done by users are persisted and can be accessed through the activity log.

List users

GET /users

# Retrieve visible users

curl "https://cloudmc_endpoint/api/v1/users" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data":[{
    "id": "e83540c7-75a0-4715-96dc-c10a364e0390",
    "userName": "habsgoalie123",
    "firstName": "Carey",
    "lastName": "Price",
    "email": "gohabsgo@cloud.mc",
    "creationDate": "2017-08-15T12:00:00.000Z",
    "status": "ACTIVE",
    "organization": {
      "id": "8e3393ce-ee63-4f32-9e0f-7b0200fa655a",
      "name": "Canadiens"
    },
    "roles": [
      {
        "id": "cdaaa9d0-304e-4063-b1ab-de31905bdab8",
        "name": "End-User"
      },
      {
        "id": "fe6d2614-3c33-447c-96f2-c79f67f5fd19",
        "name": "Environment Admin",
        "environment": {
          "id": "afcafd98-0287-4139-bb77-f29ab0549eaa"
        }
      }
    ]
  }]
}

Retrieve information about users you have access to. If you want access to other users in your organization or sub-organizations, you will need to be assigned the Users read permission. Without this permission, you will only see your own user in the list.

Attributes
id UUID	The id of the user.
userName string	The username of the user.
firstName string	The first name of the user.
lastName string	The last name of the user.
email string	The email of the user.
creationDate string	The date in ISO 8601 that the user was created.
status string	The current status of the user.
organization Organization	The organization to which the user belongs.
roles Array[Role]	The system and environments roles that are assigned to the user. includes: id, name and environment.id

Retrieve a user

GET /users/:id

# Retrieve visible user
curl "https://cloudmc_endpoint/api/v1/users/fdf60a19-980d-4380-acab-914485111305" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data":{
    "id": "fdf60a19-980d-4380-acab-914485111305",
    "userName": "frodo",
    "firstName": "Frodo",
    "lastName": "Baggins",
    "email": "frodo@cloud.mc",
    "creationDate": "2017-08-15T12:00:00.000Z",
    "status": "ACTIVE",
    "organization": {
      "id": "c64dcd1d-9123-45e5-ad00-5d635c49176b",
      "name": "The Shire"
    },
    "environments": [{
      "id": "55724a36-4817-4cd3-927e-57d8a8b41eb8",
      "name": "hobbiton"
    }],
    "roles": [
      {
        "id": "5f0a4f20-3537-4bcd-81fe-2b74fd4c07e0",
        "name": "End-User"
      },
      {
        "id": "0b9159cd-81ac-48d1-be8a-7595a1617c94",
        "name": "Read-Only",
        "environment": {
          "id": "55724a36-4817-4cd3-927e-57d8a8b41eb8"
        }
      }
    ]
  }
}

Retrieve information about a specific user. If you want access to other users in your organization or sub-organizations, you will need to be assigned the Users Read permission.

Attributes
id UUID	The id of the user.
userName string	The username of the user.
firstName string	The first name of the user.
lastName string	The last name of the user.
email string	The email of the user.
creationDate string	The date in ISO 8601 that the user was created.
status string	The current status of the user.
organization Organization	The organization to which the user belongs.
environments Array[Environment]	The environments the user is member of. includes: id, name
roles Array[Role]	The system and environments roles that are assigned to the user. includes: id, name and environment.id

Create user

POST /users

# Create a user

curl -X POST "https://cloudmc_endpoint/api/v1/users" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
  "userName": "vader42",
  "firstName": "Anakin",
  "lastName": "Skywalker",
  "email": "vader42@cloud.mc",
  "organization": {
    "id": "645cf4ce-3699-40c5-a1a8-0b3e945f49ee"
  },
  "roles": [
    {
      "id": "dd01c908-371c-4ec5-9fd7-80b1bfac8975"
    }
  ]
}

Create a user in a specific organization. There's two different types of role you can assign to the user. A system role will determine the set of system permissions the user will have. An environment role will give the user access to an environment and will determine what he can see and do in that environment. You will need the Create a new user permission to execute this operation.

Required
userName string	Username of the new user. Should be unique across the organization.
firstName string	First name of the user.
lastName string	Last name of the user.
email string	Email of the user. Should be unique across the organization.

Optional
organization Organization	Organization in which the user will be created. Defaults to your organization. required: id
roles Array[Role]	The system and environment roles to give to the user. required: id

Returns

The responses' data field contains the created user with its id.

Update user

PUT /users/:id

# Update a user
curl -X PUT "https://cloudmc_endpoint/api/v1/users/fdf60a19-980d-4380-acab-914485111305" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
  "userName": "spidey1",
  "firstName": "Peter",
  "lastName": "Parker",
  "email": "spidey1@cloud.mc",
  "roles": [
    {
      "id": "dd01c908-371c-4ec5-9fd7-80b1bfac8975"
    }
  ]
}

Update a specific user. It is important to note that updating the list of roles will override the previous one. You will the Users update permission to execute this operation.

Optional
userName string	The new username of the user. Should be unique across the organization.
firstName string	The new first name of the user.
lastName string	The new last name of the user.
email string	The new email of the user. Should be unique across the organization.
roles Array[Role]	The new list of system or environment roles to give to the user. This will override the previous list of roles. required: id

Returns

The responses' data field contains the updated user.

Delete user

DELETE /users/:id

# Delete a user
curl "https://cloudmc_endpoint/api/v1/users/fdf60a19-980d-4380-acab-914485111305" \
   -X DELETE -H "MC-Api-Key: your_api_key"

Delete a specific user. You will need the Delete an existing user permission to execute this operation.

Unlock user

POST /users/:id/unlock

# Unlock a user that was locked from the system
curl "https://cloudmc_endpoint/api/v1/users/fdf60a19-980d-4380-acab-914485111305/unlock" \
   -X POST -H "MC-Api-Key: your_api_key"

A user with 10 consecutive unsuccessful logins will be automatically locked by our system. This API can be used to unlock a user in this situation. You will need the Unlock user permission to execute this operation.

Roles

Roles have a number of permissions associated with them and are bound to users with a given scope. They are associated to users through role bindings.

List Roles

GET /roles

Retrieves a list of roles visible to the caller. The user does not have to have explicit access to that role for it to be returned. If a user's permissions on a given context context include all cumulative permissions for all roles a user is bound to that role will be returned in the roles api call.

Example: If a user has a role with env:<entity>:read and env:<entity>:create and another role exists with just env:<entity>:read it will be returned in the API call.

# Retrieve all env-scoped roles applicable to this environment 
curl "https://cloudmc_endpoint/rest/roles?v=v2&environment_id=4865a023-1dd5-45a3-a23d-e952ceb7a44a&filter_scope=ENV" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
   "data":[
      {
         "creationDate":"2019-03-11T22:16:15.000Z",
         "version":1,
         "isSystem":false,
         "isDefault":true,
         "deleted":false,
         "permissions":[
            {
               "name":"env:*:*"
            }
         ],
         "name":"editor",
         "alias":"editor",
         "id":"b230cc47-3fad-4759-8ad2-de80bc6ac7e8",
         "isFixed":true,
         "defaultScope":"ENV"
      },
      {
         "creationDate":"2019-03-11T22:16:12.000Z",
         "version":1,
         "isSystem":false,
         "isDefault":false,
         "deleted":false,
         "permissions":[
            {
               "name":"env:*:read"
            }
         ],
         "name":"viewer",
         "alias":"viewer",
         "id":"f405a594-56c7-43d4-b790-ab8c616253fc",
         "isFixed":true,
         "defaultScope":"ENV"
      }
   ]
}

Query Params
filter_scope ScopeQualifier	Return only roles with this as the default scope.
system_only boolean	Return only system roles.
organization_id UUID	Return only roles requesting user can assign on this organization.
environment_id UUID	Filters out env-scoped roles applicated to this environment. If an environment is of a plugin type that has custom plugin roles it only returns the plugin's roles, if the environment has no plugin defined roles it returns only the default environment-scoped roles.

ScopeQualifier

• ENV
• ORG_BASE
• ORG_TREE
• ORG_SUB
• ORG_TOPLEVEL
• TAG_ANYMATCH
• GLOBAL

Environments

Environments allow you to manage resources of a specific service and to manage your users' access to them. With environment roles, you have tight control of what a user is allowed to do in your environment. A general use case of environments is to split your resources into different deployment environments (e.g. dev, staging and production). The advantage is that resources of different deployments are isolated from each other and you can restrict user access to your most critical resources.

List environments

GET /environments

# Retrieve visible environments
curl "https://cloudmc_endpoint/api/v1/environments" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "1ee5cd43-8395-4cd5-a20f-0f1e83b7f8bd",
    "name": "cheyenne_mountain",
    "description": "Environment for base at Cheyenne Mountain",
    "membership": "MANY_USERS",
    "creationDate": "2017-08-15T12:00:00.000Z",
    "organization": {
      "id": "a9f93785-0545-4876-8241-3b19b9a86721",
      "name": "sg1",
      "entryPoint": "sg1"
    },
    "serviceConnection": {
      "id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
      "name": "Compute - Québec"
    },
    "roles": [{
      "id": "951b768b-e91c-4d20-8b52-d4a2ab5a538a",
      "name": "Environment Admin",
      "isDefault": true,
      "users": [{
        "id": "9f84a6ce-7be1-4a08-a25b-edc6e57fb7e3",
        "name": "jack_oneill"
      }]
    }]
  }]
}

List environments that you have access to. It will only return environments that you're member of if you're not assigned the Environments read permission.

Attributes
id UUID	The id of the environment.
name string	The name of the environment.
description string	The description of the environment.
membership string	Type of membership of the environment. (e.g. ALL_ORG_USERS, MANY_USERS)
creationDate string	The date in ISO 8601 that the environment was created.
organization Organization	The organization of the environment. includes: id, name, entryPoint
serviceConnection ServiceConnection	The service connection of the environment. includes: id, name
roles Array[Role]	The roles of the environment with all the users assigned to them. includes: id, name, isDefault, users.id, users.name

Retrieve an environment

GET /environments/:id

# Retrieve visible environment
curl "https://cloudmc_endpoint/api/v1/environment/487a2745-bb8a-44bc-adb1-e3b048f6def2" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "487a2745-bb8a-44bc-adb1-e3b048f6def2",
    "name": "galactica",
    "description": "Environment for the Galactica",
    "membership": "MANY_USERS",
    "creationDate": "2017-08-15T12:00:00.000Z",
    "organization": {
      "id": "a3340a89-8f60-407d-8a49-f5cfe81eef8f",
      "name": "kobol",
      "entryPoint": "kobol"
    },
    "serviceConnection": {
      "id": "adfbdb51-493b-45b1-8802-3f6327afb9e6",
      "name": "Compute - Québec"
    },
    "users": [{
      "id": "6e84ab70-4c62-4db1-bbd8-343636a34647",
      "userName": "starbuck"
    }],
    "roles": [{
      "id": "b04b8a7c-6e89-4dba-9734-74d9f1b7be04",
      "name": "Environment Admin",
      "isDefault": true,
      "users": [{
        "id": "6e84ab70-4c62-4db1-bbd8-343636a34647",
        "name": "starbuck"
      }]
    }]
  }
}

Retrieve an environment you have access to. You can always retrieve environments that you're a member of but to access other environments you will need the Environments read permission.

Attributes
id UUID	The id of the environment.
name string	The name of the environment.
description string	The description of the environment.
membership string	Type of membership of the environment. (e.g. ALL_ORG_USERS, MANY_USERS)
creationDate string	The date in ISO 8601 that the environment was created.
organization Organization	The organization of the environment. includes: id, name, entryPoint
serviceConnection ServiceConnection	The service connection of the environment. includes: id, name
users Array[User]	The users that are members of the environment. includes: id, username
roles Array[Role]	The roles of the environment with all the users assigned to them. includes: id, name, isDefault, users.id, users.name

Create environment

POST /environments

# Create an environment

curl -X POST "https://cloudmc_endpoint/api/v1/environments" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
  "name": "glados",
  "description": "Environment property of Aperture Science",
  "membership": "MANY_USERS",
  "organization": {
    "id": "2fd60d6f-1fee-4fe5-8ec6-46d8776acc6f"
  },
  "serviceConnection": {
    "id": "7f0fa906-490a-467b-bc44-e2382d43015e"
  },
  "roles": [{
    "name": "Environment Admin",
    "isDefault": true,
    "users": [{
      "id": "73b17dab-1705-45f1-84e2-997e2af5641b"
    }]
  }]
}

Create a new environment in a specific service and organization. You will need the Environments create permission to execute this operation.

Required
name string	The name of the new environment. Should be unique in the environment and only contain lower case characters, numbers, dashes and underscores.
description string	The description of the new environment.
serviceConnection ServiceConnection	The service connection that the environment should be created in. required: id

Optional
organization Organization	The organization that the environment should be created in. Defaults to your organization. required: id
membership string	Type of membership of the environment. ALL_ORG_USERS will add every user in the organization to this environment with the default role. MANY_USERS will allow you to choose the users you want in the environment and assigned them specific roles. Defaults to MANY_USERS.
roles Array[Role]	The roles of the environment and the users assigned to them. Also, defines the default role of the environment. required: name, users.id optional: isDefault

The responses' data field contains the updated environment.

Update environment

PUT /environments/:id

# Update an environment
curl -X POST "https://cloudmc_endpoint/api/v1/environments/f9dea588-d7ab-4f42-b6e6-4b85f273f3db" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
  "name": "skynet-beta",
  "description": "Environment for the Skynet project",
  "roles": [{
    "id": "f9dea588-d7ab-4f42-b6e6-4b85f273f3db",
    "users": [{
      "id": "07e02355-d05b-47cf-860d-f69cf0432276"
    }]
  }]
}

Optional
name string	The updated name of the environment. Should be unique in the environment and only contain lower case characters, numbers, dashes and underscores.
description string	The updated description of the environment.
membership string	Type of membership of the environment. ALL_ORG_USERS will add every user in the organization to this environment with the default role. MANY_USERS will allow you to choose the users you want in the environment and assigned them specific roles. Defaults to MANY_USERS.
roles Array[Role]	Update the users roles in the environment. Also, can also update the default role. required: name, users.id optional: isDefault

You will need the Environments update permission to execute this operation.

Delete environment

DELETE /environments/:id

# Delete an environment
curl "https://cloudmc_endpoint/api/v1/environments/f9dea588-d7ab-4f42-b6e6-4b85f273f3db" \
   -X DELETE -H "MC-Api-Key: your_api_key"

Delete a specific environment. You will need a role with the Delete an existing environment permission to execute this operation.

Resource commitments

Resource commitments allow you to set specific commitment levels on cloud resources available on a service-connection. This assures commitment to a specific set of resources on a fixed monthly price. Any additional resource usage will be billed on the utility price defined by the CMC pricing. Commitments can either be restricted to a specific date range or be un-restricted with no end date. Whilst the commitment price is decided by the pre-defined pricing, various discounts can be given on the resource utility price. Resource commitments allow CloudMC users to receive services at fixed discounted rates whilst enabling additional usage at utility cost.

List resource commitments

GET /resource_commitments

# Retrieve visible resource commitments
curl "https://cloudmc_endpoint/api/v1/resource_commitments" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "f5dc7647-71e6-4b9b-998a-c0e4d38bf2e6",
    "displayName": "CRB-SYSTEM-1",
    "creationDate": "2019-05-24T18:02:01.000Z",
    "startDate": "2019-05-16T00:00:00Z",
    "endDate": "2019-05-24T00:00:00Z",
    "pricingMethod": "FIXED_MONTHLY",
    "currency": "CAD",
    "monthlyPrice": 20.0,
    "effectiveDiscount": 92.39,
    "billableHoursPerMonth": 730,
    "billingDay": 16,
    "resourceCommitmentDetails": [
      {
        "id": "08125b3c-3b25-4585-910b-c1a0dc53010a",
        "name": "CustomDoF",
        "primaryType": "6",
        "secondaryType": "CustomDoF",
        "commitment": 0,
        "discountPercent": 0,
        "unit": "gigabyte",
        "labelKey": "cloudstack.volume"
      },
      {
        "id": "0bf1a48d-f807-4821-8247-2eb9a3128091",
        "primaryType": "3",
        "commitment": 0,
        "discountPercent": 0,
        "unit": "unit",
        "labelKey": "cloudstack.ipAddress"
      },
      { ... },
      { ... },
      { ... }
    ],
    "serviceConnection": {
      "name": "dev1-cloudstack",
      "id": "cb511a38-eab5-4a2e-969b-04e129c98415",
      "type": "cloudstack"
    },
    "organization": {
      "name": "System",
      "id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
    },
    "version": 1,
    "deleted": false
  }, 
  {
    "id": "51c01cfe-f0d5-4a3d-841d-35ec2b7df9cc",
    "displayName": "CRB-SYSTEM-2",
    ....
  }]
}

List all the resource commitments that you have access to. You can only view resource commitments if you have been assigned either the Usage: View or the Commitments: Manage permission. If you have Usage: View access then you will only be able to see the commitments specific to your organization. Having the Commitments: Manage permission lets you see all resource commitments in the system.

An array of resource commitments with the following attributes are returned.

Attributes
id UUID	The id of the resource commitment.
displayName string	The name of the resource commitment.
creationDate string	The date in ISO 8601 that the resource commitment was created.
startDate string	The date in ISO 8601 from when the resource commitment becomes active.
endDate string	The date in ISO 8601 until when the resource commitment will be active. optional: if not present then the commitment has no end date
pricingMethod string	One of the two following options that define how the effective price for the resource commitment is calculated. FIXED_MONTHLY: a fixed price per billing cycle VARIABLE_UTILITY_DISCOUNT: pricing with custom discount on specific resources
currency string	The currency type based on which the pricing is defined.
monthlyPrice number	The effective monthly price for this resource commitment.
effectiveDiscount number	The effective discount percentage (%) on this resource commitment.
billableHoursPerMonth number	The number hours per month based on which the monthly price is calculated. optional: not present if the pricing method is FIXED_MONTHLY
billingDay number	The day of the month based on which the billing cycle is calculated.
resourceCommitmentDetails Array [Commitment detail]	The resources on which different commitment levels (and discounts) have been set. includes: id, name, primaryType, secondaryType, commitment, discountPercent, unit, labelKey
organization Organization	The organization on whose connection the resource commitment is defined. includes: id, name
serviceConnection ServiceConnection	The service connection on which the resource commitment is defined. includes: id, name, type

Retrieve a resource commitment

GET /resource_commitments/:id

# Retrieve visible a resource commitment

curl "https://cloudmc_endpoint/api/v1/resource_commitments/fbgc7647-71e6-w69b-998a-c02rf58bf2e6" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "f5dc7647-71e6-4b9b-998a-c0e4d38bf2e6",
    "displayName": "CRB-SYSTEM-5",
    "creationDate": "2019-05-24T18:02:01.000Z",
    "startDate": "2019-05-16T00:00:00Z",
    "endDate": "2019-05-24T00:00:00Z",
    "pricingMethod": "FIXED_MONTHLY",
    "currency": "CAD",
    "monthlyPrice": 20.0,
    "effectiveDiscount": 92.39,
    "billableHoursPerMonth": 730,
    "billingDay": 16,
    "resourceCommitmentDetails": [
      {
        "id": "08125b3c-3b25-4585-910b-c1a0dc53010a",
        "name": "CustomDoF",
        "primaryType": "6",
        "secondaryType": "CustomDoF",
        "commitment": 0,
        "discountPercent": 0,
        "unit": "gigabyte",
        "labelKey": "cloudstack.volume"
      },
      {
        "id": "0bf1a48d-f807-4821-8247-2eb9a3128091",
        "primaryType": "3",
        "commitment": 0,
        "discountPercent": 0,
        "unit": "unit",
        "labelKey": "cloudstack.ipAddress"
      },
      { ... },
      { ... },
      { ... }
    ],
    "serviceConnection": {
      "name": "dev1-cloudstack",
      "id": "cb511a38-eab5-4a2e-969b-04e129c98415",
      "type": "cloudstack"
    },
    "organization": {
      "name": "System",
      "id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
    },
    "version": 1,
    "deleted": false
  }
}

Retrieve a specific resource commitment you have access to. You can only retrieve the resource commitment if you have either the Usage: View permission on the organization in which the commitment is defined or the Commitments: Manage permission.

Attributes
id UUID	The id of the resource commitment.
displayName string	The name of the resource commitment.
creationDate string	The date in ISO 8601 that the resource commitment was created.
startDate string	The date in ISO 8601 from when the resource commitment becomes active.
endDate string	The date in ISO 8601 until when the resource commitment will be active. optional: if not present then the commitment has no end date
pricingMethod string	One of the two following options that define how the effective price for the resource commitment is calculated. FIXED_MONTHLY: a fixed price per billing cycle VARIABLE_UTILITY_DISCOUNT: pricing with custom discount on specific resources
currency string	The currency type based on which the pricing is defined.
monthlyPrice number	The effective monthly price for this resource commitment.
effectiveDiscount number	The effective discount on this resource commitment.
billableHoursPerMonth number	The number hours per month based on which the monthly price is calculated. optional: not present if the pricing method is FIXED_MONTHLY
billingDay number	The day of the month based on which the billing cycle is calculated.
resourceCommitmentDetails Array [Commitment detail]	The resources on which different commitment levels (and discounts) have been set. includes: id, name, primaryType, secondaryType, commitment, discountPercent, unit, labelKey
organization Organization	The organization on whose connection the resource commitment is defined. includes: id, name
serviceConnection ServiceConnection	The service connection on which the resource commitment is defined. includes: id, name, type

Create a resource commitment

POST /resource_commitments

# Create a resource commitment

curl -X POST "https://cloudmc_endpoint/api/v1/resource_commitments" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
  "displayName": "NEW-RESOURCE-COMMITMENT",
  "startDate": "2019-05-16T00:00:00Z",
  "endDate": "2019-05-24T00:00:00Z",
  "pricingMethod": "FIXED_MONTHLY",
  "currency": "CAD",
  "monthlyPrice": 20.0,
  "billableHoursPerMonth": 730,
  "billingDay": 16,
  "resourceCommitmentDetails": [
    {
      "primaryType": "6",
      "secondaryType": "CustomDoF",
      "commitment": 0,
      "discountPercent": 0,
    },
    {
      "primaryType": "3",
      "commitment": 0,
      "discountPercent": 0,
    },
    { ... },
    { ... },
    { ... }
  ],
  "serviceConnection": {
    "id": "cb511a38-eab5-4a2e-969b-04e129c98415"
  },
  "organization": {
    "id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
  },
}

Create a new resource commitment defined on a service connection. You will need the Commitments: Manage permission to execute this operation.

Required
displayName string	The name of the resource commitment.
startDate string	The date in ISO 8601 from when the resource commitment becomes active.
endDate string	The date in ISO 8601 until when the resource commitment will be active. optional: if not present then the commitment has no end date
pricingMethod string	One of the two following options that define how the effective price for the resource commitment is calculated. FIXED_MONTHLY: a fixed price per billing cycle VARIABLE_UTILITY_DISCOUNT: pricing with custom discount on specific resources
currency string	The currency type based on which the pricing is defined.
monthlyPrice number	The effective monthly price for this resource commitment.
billableHoursPerMonth number	The number hours per month based on which the monthly price is calculated. optional: only required if the pricing method is VARIABLE_UTILITY_DISCOUNT
billingDay number	The day of the month based on which the billing cycle is calculated.
resourceCommitmentDetails Array [Commitment detail]	The resources on which different commitment levels (and discounts) have been set. must include: primaryType, secondaryType, commitment, discountPercent
organization Organization	The organization on whose connection the resource commitment is to be defined. must include: id
serviceConnection ServiceConnection	The service connection on which the resource commitment is to be defined. must include: id

The responses' data field contains the created resource-commitment.

Update resource commitment

PUT /resource_commitments/:id

# Update a resource commitment
curl -X PUT "https://cloudmc_endpoint/api/v1/resource_commitments/fbgc7647-71e6-w69b-998a-c02rf58bf2e6" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body"

Request body example:

{
  "id": "ef17768a-c037-4a8a-8f12-f4595dd84ca0",
  "displayName": "COMMITMENT-TO-UPDATE",
  "startDate": "2019-06-06T00:00:00Z",
  "endDate": "2019-07-07T00:00:00Z",
  "pricingMethod": "FIXED_MONTHLY",
  "currency": "CAD",
  "billingDay": 6,
  "monthlyPrice": 335,
  "billableHoursPerMonth": 730,
  "resourceCommitmentDetails": [
    {
      "id": "125e01c7-6486-46be-8cb8-f0da46c7dbbd",
      "commitment": 5,
      "primaryType": "1",
      "secondaryType": "5d94cfdc-87cf-4f0a-9083-bf92e5caa2cd_mem",
      "discountPercent": 0
    },
    {
      "id": "6293b5ba-4fa2-49c7-b51d-4129ae0ae340",
      "commitment": 5,
      "primaryType": "1",
      "secondaryType": "c85a8899-e2b7-4786-9304-481533665215",
      "discountPercent": 0
    },
    { ... },
    { ... },
    { ... }
  ],
  "creationDate": "2019-06-06T20:06:28.000Z",
  "organization": {
    "id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
  },
  "serviceConnection": {
    "id": "cb511a38-eab5-4a2e-969b-04e129c98415"
  }
}

Attributes
id UUID	The id of the resource commitment.
displayName string	The name of the resource commitment.
startDate string	The date in ISO 8601 from when the resource commitment becomes active.
endDate string	The date in ISO 8601 until when the resource commitment will be active. optional: if not present then the commitment has no end date
pricingMethod string	One of the two following options that define how the effective price for the resource commitment is calculated. FIXED_MONTHLY: a fixed price per billing cycle VARIABLE_UTILITY_DISCOUNT: pricing with custom discount on specific resources
currency string	The currency type based on which the pricing is defined.
monthlyPrice number	The effective monthly price for this resource commitment.
billableHoursPerMonth number	The number hours per month based on which the monthly price is calculated. optional: only required if the pricing method is VARIABLE_UTILITY_DISCOUNT
billingDay number	The day of the month based on which the billing cycle is calculated.
resourceCommitmentDetails Array [Commitment detail]	The resources on which different commitment levels (and discounts) have been set. includes: id, primaryType, secondaryType, commitment, discountPercent
organization Organization	The organization on whose connection the resource commitment to be edited is defined. includes: id
serviceConnection ServiceConnection	The service connection on which the resource commitment to be edited is defined. includes: id

The responses' data field contains the created resource-commitment. You will need the Commitments: Manage permission to execute this operation.

Delete resource commitment

DELETE /resource_commitments/:id

# Delete a resource commitment

curl "https://cloudmc_endpoint/api/v1/resource_commitments/fbgc7647-71e6-w69b-998a-c02rf58bf2e6" \
   -X DELETE -H "MC-Api-Key: your_api_key"

Delete a specific resource commitment. You will need a role with the Commitments: Manage permission to execute this operation.

Usage

List organization usage summary

GET /usage_summary/organizations/:id

# Retrieve usage summary in JSON
curl "https://cloudmc_endpoint/api/v1/usage_summary/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5?start_date=2017-05-01&end_date=2017-05-15&format=json" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [{
    "organizationId": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e",
    "serviceConnectionId": "beeba736-0451-49b0-8020-8b93ed5abb35",
    "serviceConnectionPricingId": "e37cc44a-47b6-4a26-81f5-1dbf85433e36",
    "utilityCost": 0.66,
    "utilityUsage": 5.49999878,
    "startDate": "2017-05-01T00:00:00.000Z",
    "endDate": "2017-05-01T01:00:00.000Z",
    "usageType": "1",
    "secondaryType": "RAM"
  }]
}

# Retrieve usage summary in CSV
curl "https://cloudmc_endpoint/api/v1/usage_summary/organizations/03bc22bd-adc4-46b8-988d-afddc24c0cb5?start_date=2017-05-01&end_date=2017-05-15&format=csv" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

organizationId,serviceConnectionId,startDate,endDate,usageType,secondaryType,serviceConnectionPricingId,utilityCost,utilityUsage
52fd201e-aa82-4a27-86b3-ea9650a7fb1e,beeba736-0451-49b0-8020-8b93ed5abb35,2017-05-01T00:00:00.000Z,2017-05-01T01:00:00.000Z,1,RAM,e37cc44a-47b6-4a26-81f5-1dbf85433e36,0.660000,5.49999878

Retrieve the usage summary records for an organization and all of its sub-organizations for a specific period. The response can be in JSON (default) or CSV format. Additionally, you can aggregate these records using the different query parameters available.

Note: Old records are aggregated by day instead of hour. If you try to query those records per hour, then you will receive an empty list.

Attributes
organizationId UUID	Id of the organization.
serviceConnectionId UUID	Id of the service connection.
serviceConnectionPricingId UUID	Id of the service connection pricing.
utilityCost string	Utility cost of the record (aggregated per the period).
utilityUsage string	Utility usage of the record.
startDate string	Start date of the record in ISO 8601.
endDate string	End date of the record in ISO 8601.
usageType string	Usage type of the record.
secondaryType string	Secondary type of the record.

Note: The utilityUsage reported by this API is the total usage recorded for the specified period. The resource commitment is not taken into account for this endpoint but is outlined in the endpoint /top_level/organizations/{org_id} below.

Query Parameters (required)
start_date String	Start date (inclusive). Should have the following format YYYY-MM-DD.
end_date String	End date (exclusive). Should have the following format YYYY-MM-DD.

Query Parameters
service_connection_id UUID	Show usage summary for this service connection.
include_sub_orgs boolean	Include usage summary of all its sub-organizations. Defaults to false.
include_cost boolean	Include the utility cost and service connection pricing id fields. Defaults to true.
include_free_usage boolean	Include all summary records that has no cost associated to it (i.e. utilityCost == 0). Defaults to true.
combine_usage_types boolean	Sums up the utility cost per organization and service connection. The following fields are removed from the output: serviceConnectionPricingId, usageType, secondaryType, utilityUsage.
period String	The period on which the aggregation is made. HOUR, DAY or PERIOD. The default is HOUR.
format String	JSON or CSV. Defaults to JSON.
include_deleted boolean	Will find usage of an organization that may have been deleted.

List top level organization usage summary

GET /usage_summary/top_level/organizations/:id

# Retrieve usage summary in JSON
curl -X GET \
  'https://cloudmc_endpoint/rest/usage_summary/top_level/organizations/52fd201e-aa82-4a27-86b3-ea9650a7fb1e?start_date=2019-03-12&end_date=2019-03-13' \
  -H 'content-type: application/json' \
  -H 'mc-api-key: your_api_key' \

The above command returns a JSON structured like this:

{
  "data": [
   {
     "organizationId": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e",
     "serviceConnectionId": "818fa22d-1621-4cf3-87c3-4c10b146524c",
     "serviceConnectionPricingId": "c2e38b0d-9b6e-4e79-959f-731cf3d00b1a",
     "usageType": "1",
     "secondaryType": "RAM",
     "utilityCost": 0.480000,
     "utilityUsage": 3.99999910,
     "resourceCommitmentUsage": 1.0000000,
     "startDate": "2019-03-12T00:00:00Z",
     "endDate": "2019-03-12T01:00:00Z"
   }]
}

Retrieves the usage summary records for top level organization and its sub-organizations for a specific period ensuring that usage is split between two buckets, resource commitment usage and utility usage. The response format will be in the JSON format.

Resource Commitment Usage:

The usage that is counted toward a pre assigned pool of resources defined by the Resource Commitment of the organization on a specified service connection. The resource commitment usage is capped by the resource commitment capacity which is the total amount of resource allocated to the organization.

Utility Usage:

Usage that bursts outside of the allocated resource commitment if one exists. Note that utility usage will only appear in the response when the actualUsage > resourceCommitmentsUsage. Note that the resourceCommitmentUsage will always be less than or equal to the resourceCommitmentCapacity which is defined by the commitment.

The following will always hold: utilityUsage + resourceCommitmentUsage = actualUsage

Attributes
organizationId UUID	Id of the organization.
serviceConnectionId UUID	Id of the service connection.
serviceConnectionPricingId UUID	Id of the service connection pricing.
utilityCost string	Utility cost of the record (aggregated per the period).
utilityUsage string	Utility usage of the record.
resourceCommitmentUsage string	The amount of usage that was counted toward the commitment capacity defined by the resource commitment.
startDate string	Start date of the record in ISO 8601.
endDate string	End date of the record in ISO 8601.
usageType string	Usage type of the record.
secondaryType string	Secondary type of the record.

Query Parameters (required)
start_date String	Start date (inclusive). Should have the following format YYYY-MM-DD.
end_date String	End date (exclusive). Should have the following format YYYY-MM-DD.

Query Parameters
service_connection_id UUID	Show usage summary for this service connection.
include_sub_orgs boolean	Include usage summary of all its sub-organizations. Defaults to false.
include_cost boolean	Include the utility cost and service connection pricing id fields. Defaults to true.
include_free_usage boolean	Include all summary records that has no cost associated to it (i.e. utilityCost == 0). Defaults to true.
combine_usage_types boolean	Sums up the utility cost per organization and service connection. The following fields are removed from the output: serviceConnectionPricingId, usageType, secondaryType, utilityUsage.
period String	The period on which the aggregation is made. HOUR, DAY or PERIOD. The default is HOUR.
include_deleted boolean	Will find usage of an organization that may have been deleted.

Retrieve service usage

GET /service/usage

# Retrieve customer usage
curl -X POST "https://cloudmc_endpoint/rest/service/usage?page=1&page_size=1" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
 "data": {
  "records": [
   {
    "id": "a855e912f682b398379eefd5bbeffa2e:805",
    "usageType": "memory_type",
    "usage": 143.99833333333333,
    "unit": "gibibyte-hour",
    "connectionId": "081ffa1f-1531-4dd5-a7e2-070e560409ce",
    "connectionName": "Edge Services",
    "organizationId": "ca785487-5e22-4bac-ab01-187260b0d0cb",
    "organizationName": "Cox",
    "environmentId": "207ed06a-5b20-4d79-a7eb-d9ac4878519b",
    "environmentName": "jdias-test-jason",
    "startDate": "2022-01-01T00:00:00Z",
    "endDate": "2022-01-02T00:00:00Z",
    "fields": {
     "PoP": "Phoenix",
     "type": "Container",
     "region": "NA"
    },
    "metricType": "GAUGE",
    "metadata": {
     "serviceCode": "edge-cloud-beta",
     "account_id": "69b60c67-6175-4515-bb65-033108305d66",
     "stackId": "cb9caf46-323f-402c-b173-742ba464e50e",
     "service_account_id": "657c6671-872f-4590-8e31-a9bc6589918b",
     "stackSlug": "jdias-test-jaso-7vhhr3lplg-env",
     "client_id": "4e0c5f157c5d089671a57c4132205667",
     "credential_id": "8b4e6d56-216b-4c70-8ce6-d283042aa3b9"
    }
   }
  ],
  "metadata": {
   "totalCount": 13922,
   "totalPageCount": 13923,
   "count": 1,
   "page": 1
  }
 }
}

Record Attributes	Description
id String	The id of the record.
usageType String	The type of the underlying usage.
usage Number	The amount of usage within this usage records period.
unit String	The unit attributed to the usage.
connectionId String	The id of the connection on which this usage was generated.
connectionName String	The name of the connection on which this usage was generated.
organizationId String	The id of the organization on which this usage was generated.
organizationName String	The name of the organization on which this usage was generated.
environmentId String	The id of the environment on which this usage was generated.
environmentName String	The name of the environment on which this usage was generated.
startDate ISO8601 Date Time	The start date of the record (inclusive)
endDate ISO8601 Date Time	The end date of the record (exclusive)
fields Object	Attributes of the underlying resource that created this usage
metricType String	The type of metric being summarized in this record. [COUNTER,GAUGE]. Counter accumulates over time. Gauge types indicate a particular amount of usage during record duration and fluxate up and down.
metadata Object	Attributes of the underlying environment under which this usge was created.

Metadata Attributes	Description
totalCount Number	The total number of records satisfying the query.
totalPageCount Number	The total number of pages.
count Number	The number of records returned on this page only.
page Number	The page returned. Always the same as the page requested.

Query Options

Optional Query Parameters	Description	Default Behaviour (when not specified)
organization_id	Retrieve the usage of a specific organization only	All organizations the caller has visibility on
environment_Id	Retrieve the usage of a specific environment only	All environments the caller has visibility on
connection_id	Retrieve the usage of a specific connection only	All connections the caller have visibility on
usage_type	Retrieve the usage of a specific usage type only	All usage types
start_date (inclusive)	Retrieve the usage starting from the requested date	The last 7 days or for the granularity specified. I.e. last year if YEARLY, last month if MONTHLY
end_date	Retrieve the usage up to the specific date only	The time of the request

To retrieve data as a json response supply the application/json Accept header in your request. For example:

curl -X POST "https://cloudmc_endpoint/rest/service/usage" \
   -H "MC-Api-Key: your_api_key" \
   -H "Accept: application/json"

Query parameters (application/json)	Description	Default Behaviour (when not specified)
page	The page of data to retrieve [1,...,N]	1
page_size	The size of the page to retrieve (max: 1000)	100
granularity1	[YEARLY, MONTHLY, DAILY, HOURLY]. Transforms the data into the requested granularity	No transformation is made
next_page_token	For requests that specify a granularity, may be used to retrieve the next page of results.

¹ Note: a granularity query is expensive and may take time. When specifying a granularity, traditional paging is not performed. Up to 65,536 results may be returned. If there are more than 65,536 results only the first 65,536 results will be returned and subsequent records maybe retrieved by specifying the next_page_token query param in the request. The token will be provided in the response.

{
  "records": [...],
  "metadata": {
    "count": 65536,
    "next_page_token": "ewogICJzb3J0IjogInN0YXJ0RGF0ZSIsCiAgInZhbHVlIjogMTY1MDU1NTQ0OQp9"
  }
}

To retrieve data as a csv response supply the text/csv Accept header in your request. For example:

curl -X POST "https://cloudmc_endpoint/rest/service/usage" \
   -H "MC-Api-Key: your_api_key" \
   -H "Accept: text/csv"

Note that granularity and paging (of any kind) are not supported for CSV response type.

Monetization

Reports

Reports using the pricing v2 engine.

Get an organization report

GET /reports/organization_pricing?organization_id=:id&start_date:=end_date=&end_date=:end_date

Retrieves a list of usage grouped by currency and containing categories and their products. There is a cost sum at the currency, category and product level of granularity. Generates a report using applied pricings from the closest reseller to the organization, not including itself.

Query Parameters

Required
start_date String	An ISO-8601 instant format string representing the start of the usage. This will included any usage who's usage start date is greater than, inclusively, the provided instant.
end_date String	An ISO-8601 instant format string representing the end of the usage. This will include any usage who's usage end date is less than, non-inclusively, the provided instant.

Optional
organization_id UUID	The organization for which you're building the report. If not passed will default to the calling user's organization.
service_connection_id UUID	Only return usage for the selected service connection id.
environment_id UUID	Only return usage for the selected environment id. Needs to be provided along with the service_connection_id.

curl --request GET \
  --url 'https://cloudmc_endpoint/api/v2/reports/organization_pricing?start_date=2021-03-30T00%3A00%3A00.000Z&end_date=2021-04-01T23%3A59%3A59.999Z' 
  \
  --header 'MC-Api-Key: your_api_key'

{
  "data": {
    "currencies": [
      {
        "currency": "CAD",
        "total": "432.00",
        "categories": [
          {
            "name": {
              "en": "Networking",
              "fr": "Networking"
            },
            "products": [
              {
                "sku": "PUBLIC_IP",
                "name": {
                  "en": "Public IP",
                  "fr": "Public IP"
                },
                "cost": "432.00",
                "usage": "465.0000",
                "period": "HOUR",
                "unit": {
                  "unit": "HOUR",
                  "name": {}
                },
                "pricingTiers": [
                  {
                    "usage": "300.0000",
                    "price": "1.00",
                    "cost": "300.00"
                  },
                  {
                    "usage": "165.0000",
                    "price": "0.80",
                    "cost": "132.00"
                  }
                ]
              }
            ],
            "subTotal": "432.00"
          }
        ]
      }
    ],
    "startDate": "2021-03-30T00:00:00Z",
    "endDate": "2021-04-01T23:59:59.999Z",
    "reportGenerated": true
  }
}

Organization Report Attributes
currencies Array[Object]	Returns an array of currencies for the usage.
currencies.currency string	The short-name of the currency.
currencies.total string	A string containing the total of all usage.
currencies.categories Array[Object]	An array of category objects. Contains all categories that had usage for the period.
currencies.categories.name Object	A map of short language codes to their translated category names.
currencies.categories.subTotal string	A string with the subtotal of usage for the category. It is the summed up product usage.
currencies.categories.products Object	A map of short language codes to their translated category names.
currencies.categories.products.sku string	A unique string representing the sku for a product.
currencies.categories.products.name Object	The name object in each language for the product name.
currencies.categories.products.cost string	A string of the summed up total cost for the product.
currencies.categories.products.usage Object	A string of the summed up total usage for the product.
currencies.categories.products.price Object	A string representing the average unit price over the preriod.
currencies.categories.products.period string	The period for the product capture. Possible values: HOURS, MONTH.
currencies.categories.products.unit Object	The unit object of the product.
currencies.categories.products.unit.unit Object	The unit value of the product.
currencies.categories.products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
currencies.categories.products.pricingTiers Array[Object]	The cost and usage breakdown per pricing tier configured on the product. Only pricing tiers with usage for the period are shown.
currencies.categories.products.pricingTiers.usage string	The total usage gathered for the given pricing tier configured on the product.
currencies.categories.products.pricingTiers.cost string	The total cost incurred for the given pricing tier configured on the product.
currencies.categories.products.pricingTiers.price string	The unit price charged per usage unit for the given pricing tier configured on the product.
startDate string	An ISO-8601 instant format string representing the start of the report.
endDate string	An ISO-8601 instant format string representing the end of the report.
reportGenerated boolean	Whether or not a report could be generated for this time period.

Get an organization report as a csv

GET /reports/organization_pricing?organization_id=:id&start_date:=end_date=&end_date=:end_date&language=:language&currency=:currency

Retrieves a flat list of product with usage and cost along with other details in a csv format.

# Retrieve organizatio usage
curl  --request GET \
  --url "https://cloudmc_endpoint/api/v2/reports/organization_pricing?start_date=2021-07-01T00%3A00%3A00.000Z&end_date=2021-07-31T23%3A59%3A59.999Z&organization_id=a01716d0-f748-447d-94e9-60ba46753d1a&language=en&currency=CAD" \
  -H 'Accept: text/csv ' \
  -H "MC-Api-Key: your_api_key"

The response is a list of products with their usage and cost, with the first line as a header, for the given organization and period.

The format of the response is a CSV with , used as the delimiter.

organization,account_id,category,sku,product_name,usage,unit,currency,cost,start_date,end_date
organizationName,12345,Compute,container_memory,Container memory,1097.272800,HOUR,CAD,2194.55,2021-07-01T00:00:00Z,2021-07-31T23:59:59.999Z       

Query Parameters

Required
start_date String	An ISO-8601 instant format string representing the start of the usage. This will included any usage who's usage start date is greater than the provided instant inclusively.
end_date String	An ISO-8601 instant format string representing the end of the usage. This will include any usage who's usage end date is less than, non-inclusively, the provided instant.
language UUID	Language to use for the report fields (but not the headers). Expected values are "en" (English), "fr" (French) or "es" (Spanish).

Optional
organization_id UUID	The organization for which the report will be built. If not passed will default to the calling user's organization.
service_connection_id UUID	Only return usage for the selected service connection id.
environment_id UUID	Only return usage for the selected environment id. Needs to be provided along with the service_connection_id.
currency String	The currency of usage.

Report Attributes
organization String	The organization name.
custom_field_1 String	The organization custom field (ex: account ID). Configured in the reseller billing settings. There can be more than one custom field.
category String	The product category.
sku String	The SKU of the product.
product_name Object	The name object in each language for the product name.
usage String	The total usage of the product.
unit String	The name of the unit of the product.
currency String	The short-name of the currency.
cost string	The total cost of the product.
startDate string	An ISO-8601 instant format string representing the start of the report.
endDate string	An ISO-8601 instant format string representing the end of the report.

Get a customer's report

GET /reports/customers?start_date:=end_date=&end_date=:end_date

Retrieves a list of all usage for the provided reseller organization and all of it's suborgs.

Query Parameters

Required
start_date String	An ISO-8601 instant format string representing the start of the usage. This will included any usage who's usage start date is greater than, inclusively, the provided instant.
end_date String	An ISO-8601 instant format string representing the end of the usage. This will include any usage who's usage end date is less than, non-inclusively, the provided instant.

Optional
organization_id UUID	The reseller for which you're building the report. If not passed will default to the calling user's organization. This organization must be a reseller.
service_connection_id UUID	Only return usage for the selected service connection id.

curl --request GET \
  --url 'https://cloudmc_endpoint/api/v2/reports/customers?start_date=2021-04-01T00%3A00%3A00.000Z&end_date=2021-04-07T23%3A59%3A59.999Z' \
  --header 'MC-Api-Key: your_api_key'

{
  "data": {
    "organizations": [
      {
        "id": "4b0c91a8-522a-4121-ac63-f9ae33be4eda",
        "name": "JasonOrg",
        "total": "5244.00",
        "currency": "CAD",
        "categories": [
          {
            "name": {
              "en": "Networking",
              "fr": "Networking"
            },
            "subTotal": "684.00"
          },
          {
            "name": {
              "en": "Disk",
              "fr": "Disk"
            },
            "subTotal": "4560.00"
          }
        ],
        "appliedPricing": {
          "id": "0495ac17-0b75-4583-af6c-c69d0d2e7289",
          "name": {
            "en": "Standard Pricing",
            "fr": "Standard Pricing"
          }
        }
      }
    ],
    "reportGenerated": true,
    "startDate": "2021-04-01T00:00:00Z",
    "endDate": "2021-04-07T23:59:59.999Z"
  }
}

Customer Report Attributes
organizations Array[Object]	Returns an array of organizations for the usage. There will be one entry per organization and applied pricing combination found for the time period.
organizations.currency string	The short-name of the currency.
organizations.total string	A string containing the total of all usage.
organizations.categories Array[Object]	An array of category objects. Contains all categories that had usage for the period.
organizations.categories.name Object	A map of short language codes to their translated category names.
organizations.categories.subTotal string	A string with the subtotal of usage for the category. It is the summed up product usage.
organizations.appliedPricing Object	The applied pricing for this organization entry.
organizations.appliedPricing.id UUID	The applied pricing for this organization entry.
organizations.appliedPricing.name Object	A map of short language codes to their translated name for the applied pricing.
startDate string	An ISO-8601 instant format string representing the start of the report.
endDate string	An ISO-8601 instant format string representing the end of the report.
reportGenerated boolean	Whether or not a report could be generated for this time period.

GET /reports/revenue_tax_report?billing_cycle=:billing_cycle&organization_id=:organization_id&language=:language

The response is a list of priced products, with the first line as a header, across all the customers of the given reseller and billing cycle.

The format of the response is a CSV with , used as the delimiter.

Query Parameters

Optional
billingCycle String	The cycle which the invoice belongs to. Format is MM-YYYY. Defaults to the latest billing cycle.
organization_id UUID	The reseller for which you're building the report. If not passed will default to the calling user's organization. This organization must be a reseller.
language UUID	Language to use for the report fields (but not the headers). Expected values are "en" (English), "fr" (French) or "es" (Spanish). Defaults to "en".

curl -X GET \
  'https://cloudmc_endpoint/api/v2/reports/customers/revenue_tax_report?billing_cycle=:billing_cycle&organization_id=:organization_id&language=:language' \
  --header 'MC-Api-Key: your_api_key'

organization,custom_field_1,custom_field_2,category,sku,usage,unit,currency,total_before_tax,tax_code,total_tax,tax_name1,tax_amount1,tax_name2,tax_amount2,invoice_number,status,due_date,credit_card_transaction_id,billing_start_date,billing_end_date,
AcmeCorp,null,null,Networking,BANDWIDTH,0.0043,GIGABYTE,USD,$0.00,SW056003,$0.00,QUEBEC QST/TVQ,$0.00,CANADA GST/TPS,$0.00,NFROFNGWHU,DRAFT,null,null,9/20/21,10/20/21,
AcmeCorp,null,null,Compute,CCM-1M02,295.935,GIGABYTE,USD,$21.90,SW056003,$3.28,QUEBEC QST/TVQ,$2.18,CANADA GST/TPS,$1.10,NFROFNGWHU,DRAFT,null,null,9/20/21,10/20/21,%         

Report Attributes
organization String	The organization name.
custom_field_1 String	The organization custom field (ex: account ID). Configured in the reseller billing settings. There can be more than one custom field.
category String	The product category.
sku String	The SKU of the product.
usage String	The total usage of the product.
unit String	The name of the unit of the product.
currency String	The short-name of the currency.
total_before_tax String	The total cost before taxes are applied.
tax_code String	The code of the tax.
total_tax String	The total tax.
tax_name1 String	The name of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax name.
tax_amount1 String	The amount of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax amount.
invoice_number String	The human-readable number of the invoice.
status String	The status of the invoice. Possible values are: USAGE_PENDING, DRAFT, ISSUED, OVERDUE, PAID, VOID.
due_date String	The date the invoice is due.
credit_card_transaction_id String	The confirmation number returned from the payment provider for the invoice.
billing_start_date String	The billing start date of the invoice.
billing_end_date String	The billing end date of the invoice.

Notification Categories

Manage notification categories.

List notification categories

GET /content/categories

# Retrieve notification categories
curl "https://cloudmc_endpoint/v2/rest/content/categories?language=:language&organization_id=:organizationId" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
    "data": [
        {
            "organizationId": "3e824205-f507-4ffe-9891-a8addf3cf0e9",
            "createdAt": "2020-10-29T14:06:50.000Z",
            "translations": [
                {
                    "language": "en",
                    "id": "1cea5fe9-3bfa-4eea-a9aa-8e8aa8f85346",
                    "text": "Test-notif-reseller",
                    "type": "title",
                    "version": 1
                },
                {
                    "language": "fr",
                    "id": "d4044366-2bf9-4c1f-9da5-e2e47b719714",
                    "text": "test-notif-reseller",
                    "type": "title",
                    "version": 1
                }
            ],
            "icon": "fa fa-envelope",
            "id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241",
            "version": 1,
            "updatedAt": "2020-10-29T14:06:50.000Z"
        }
    ]
}

List the notification categories configured for the organization.

Optional Query Parameters
organization_id UUID	The id of the organization we wish to display notification categories for. If not provided, the current user's organization id will be used.
language UUID	Language of the notification categories. Expected values are "en" (English), "fr" (French) or "es" (Spanish).

Attributes
id UUID	The id of the notification category.
organizationId UUID	The organization id of the notification category.
createdAt string	The date on which the notification category was created.
updatedAt string	The date on which the notification category was updated.
icon string	The icon used when displaying the notification category.
version integer	The notification category's version.
translations Array[Object]	The translations of the notification category content.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification category, this can only be "title".
translations.id UUID	The translation's id.
translations.version integer	The translation's version.

Retrieve notification category

GET /content/categories/:id

# Retrieve notification category
curl "https://cloudmc_endpoint/v2/rest/content/categories/:id?language=:language" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
    "data": {
        "organizationId": "3e824205-f507-4ffe-9891-a8addf3cf0e9",
        "createdAt": "2020-10-29T14:06:50.000Z",
        "translations": [
            {
                "language": "en",
                "id": "1cea5fe9-3bfa-4eea-a9aa-8e8aa8f85346",
                "text": "Test-notif-reseller",
                "type": "title",
                "version": 1
            },
            {
                "language": "fr",
                "id": "d4044366-2bf9-4c1f-9da5-e2e47b719714",
                "text": "test-notif-reseller",
                "type": "title",
                "version": 1
            }
        ],
        "icon": "fa fa-envelope",
        "id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241",
        "version": 1,
        "updatedAt": "2020-10-29T14:06:50.000Z"
    }
}

Get a specific notification category.

Optional Query Parameters
language UUID	Language of the notification categories. Expected values are "en" (English), "fr" (French) or "es" (Spanish).

Attributes
id UUID	The id of the notification category.
organizationId UUID	The organization id of the notification category.
createdAt string	The date on which the notification category was created.
updatedAt string	The date on which the notification category was updated.
icon string	The icon used when displaying the notification category.
version integer	The notification category's version.
translations Array[Object]	The translations of the notification category's content.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification category, this can only be "title".
translations.id UUID	The translation's id.
translations.version integer	The translation's version.

Create notification category

POST /content/categories/

# Create notification category
curl -X POST "https://cloudmc_endpoint/v2/rest/content/categories/" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
    "organizationId":"2cc1b5ba-2cfb-4bf9-9cb9-c67d34ba27b1",
    "icon": "fa fa-envelope",
    "translations": [
        {
            "language":"en",
            "type":"title",
            "text":"trial-ttt"
        },
        {
            "language":"fr",
            "type":"title",
            "text":"trial-tt"
        }
    ]
}

Create a notification category.

Required
organizationId UUID	The organization id of the notification category.
icon string	The icon used when displaying the notification category.
translations Array[Object]	The translations of the notification category's content.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification category, this can only be "title".

Update notification category

PUT /content/categories/:id

# Update notification category
curl -X PUT "https://cloudmc_endpoint/v2/rest/content/categories/:id" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
    "id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241",
    "organizationId":"3e824205-f507-4ffe-9891-a8addf3cf0e9",
    "icon": "fa fa-envelope",
    "translations": [
        {
            "language": "en",
            "text": "Test-notif-reseller",
            "type": "title"
        },
        {
            "language": "fr",
            "text": "test-notif-reseller",
            "type": "title"
        }
    ]
}

Update a notification category.

Required
id UUID	The id of the notification category.
organizationId UUID	The organization id of the notification category.
icon string	The icon used when displaying the notification category.
translations Array[Object]	The translations of the notification category's content.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification category, this can only be "title".

Optional
translations.id UUID	When specified, the existing translation will be modified. If not provided, a new translation will replace the existing one.

Delete notification category

DELETE /content/categories/:id

# Delete a notification category
curl "https://cloudmc_endpoint/v2/content/categories/:id" \
   -X DELETE -H "MC-Api-Key: your_api_key"

Delete a notification category. You must ensure that this category has no associated notification.

Notifications

Manage notifications.

List notifications

GET /content/notifications

# Retrieve notification categories
curl "https://cloudmc_endpoint/v2/rest/content/notifications?language=:language&organization_id=:organiationId" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
    "data": [
        {
            "publishedAt": "2020-10-29T19:27:34.299Z",
            "authorId": "15419d47-0ec4-47d5-8622-4fbb1948844f",
            "version": 1,
            "createdAt": "2020-10-29T15:04:36.134Z",
            "authorLastName": "Root",
            "authorFirstName": "Root",
            "translations": [
                {
                    "language": "en",
                    "id": "99f815c6-2aba-4462-9419-63daa67712e2",
                    "text": "system-notification",
                    "type": "title",
                    "version": 1
                },
                {
                    "language": "fr",
                    "id": "812f3b76-bc6b-4816-ace8-3e69c6e1efcd",
                    "text": "en français",
                    "type": "title",
                    "version": 1
                },
                {
                    "language": "en",
                    "id": "94c4bedb-df83-49f0-beb3-8e672e28c316",
                    "text": "system",
                    "type": "body",
                    "version": 1
                },
                {
                    "language": "fr",
                    "id": "98c1f48c-1f2b-4dc6-a43c-3f239a2473a7",
                    "text": "system",
                    "type": "body",
                    "version": 1
                }
            ],
            "deprecatedAt": "2020-11-03T20:57:00.000Z",
            "sticky": true,
            "id": "b7c6d7ca-6fef-406b-a911-bba873a99773",
            "category": {
                "organizationId": "1384d793-dae5-441c-8cc2-e78168c94018",
                "createdAt": "2020-10-29T15:01:44.000Z",
                "translations": [
                    {
                        "language": "en",
                        "id": "4840af1e-1d74-4b4f-bdda-6e04f4569142",
                        "text": "system-category",
                        "type": "title",
                        "version": 1
                    },
                    {
                        "language": "fr",
                        "id": "0bc8f49c-8f65-4319-be57-ad70cdfe144d",
                        "text": "en français",
                        "type": "title",
                        "version": 1
                    }
                ],
                "icon": "fa fa-envelope",
                "id": "2569f2cc-f1d7-4664-8439-173fedfab1c3",
                "version": 1,
                "updatedAt": "2020-10-29T19:28:22.000Z"
            },
            "splash": false,
            "updatedAt": "2020-10-29T19:27:34.462Z",
            "status": "published"
        }
    ]
}

List the notifications configured for the organization.

Optional Query Parameters
organization_id UUID	The id of the organization we wish to display notifications for. If not provided, the current user's organization id will be used.
language UUID	Language of the notification.Expected values are "en" (English), "fr" (French) or "es" (Spanish).

Attributes
id UUID	The id of the notification.
authorId UUID	The author's id.
authorFirstName string	The author's first name.
authorLastName string	The author's last name.
splash boolean	When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true.
sticky boolean	When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true.
status string	The status of the notification within it's lifecycle (draft, published, deprecated).
createdAt string	The date on which the notification was created.
updatedAt string	The date on which the notification was updated.
publishedAt string	The date on which the notification was published.
depricatedAt string	The date on which the notification will be deprecated.
version integer	The notification's version.
category Array[Notification Category]	The notification category that the notification belongs to. includes: id, organizationId, createdAt, updatedAt, translations, icon, version
translations Array[Object]	The translations of the notification category's content.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification, this can only be "title" or "body".
translations.id UUID	The translation's id.
translations.version integer	The translation's version.

Retrieve notification

GET /content/notifications/:id

# Retrieve notification category
curl "https://cloudmc_endpoint/v2/rest/content/notifications/:id?language=:language" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
    "data": {
        "publishedAt": "2020-10-29T19:27:34.299Z",
        "authorId": "15419d47-0ec4-47d5-8622-4fbb1948844f",
        "version": 1,
        "createdAt": "2020-10-29T15:04:36.134Z",
        "authorLastName": "Root",
        "authorFirstName": "Root",
        "translations": [
            {
                "language": "en",
                "id": "99f815c6-2aba-4462-9419-63daa67712e2",
                "text": "system-notification",
                "type": "title",
                "version": 1
            },
            {
                "language": "fr",
                "id": "812f3b76-bc6b-4816-ace8-3e69c6e1efcd",
                "text": "en français",
                "type": "title",
                "version": 1
            },
            {
                "language": "en",
                "id": "94c4bedb-df83-49f0-beb3-8e672e28c316",
                "text": "system",
                "type": "body",
                "version": 1
            },
            {
                "language": "fr",
                "id": "98c1f48c-1f2b-4dc6-a43c-3f239a2473a7",
                "text": "system",
                "type": "body",
                "version": 1
            }
        ],
        "deprecatedAt": "2020-11-03T20:57:00.000Z",
        "sticky": true,
        "id": "b7c6d7ca-6fef-406b-a911-bba873a99773",
        "category": {
            "organizationId": "1384d793-dae5-441c-8cc2-e78168c94018",
            "createdAt": "2020-10-29T15:01:44.000Z",
            "translations": [
                {
                    "language": "en",
                    "id": "4840af1e-1d74-4b4f-bdda-6e04f4569142",
                    "text": "system-category",
                    "type": "title",
                    "version": 1
                },
                {
                    "language": "fr",
                    "id": "0bc8f49c-8f65-4319-be57-ad70cdfe144d",
                    "text": "en français",
                    "type": "title",
                    "version": 1
                }
            ],
            "icon": "fa fa-envelope",
            "id": "2569f2cc-f1d7-4664-8439-173fedfab1c3",
            "version": 1,
            "updatedAt": "2020-10-29T19:28:22.000Z"
        },
        "splash": false,
        "updatedAt": "2020-10-29T19:27:34.462Z",
        "status": "published"
    }
}

Get a specific notification.

Optional Query Parameters
language UUID	Language of the notification. Expected values are "en" (English), "fr" (French) or "es" (Spanish).

Attributes
id UUID	The id of the notification.
authorId UUID	The author's id.
authorFirstName string	The author's first name.
authorLastName string	The author's last name.
splash boolean	When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true.
sticky boolean	When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true.
status string	The status of the notification.
createdAt string	The date on which the notification was created.
updatedAt string	The date on which the notification was updated.
publishedAt string	The date on which the notification was published.
depricatedAt string	The date on which the notification will be deprecated.
version integer	The notification's version.
category Array[Notification Category]	The notification category that the notification belongs to. includes: id, organizationId, createdAt, updatedAt, translations, icon, version
translations Array[Object]	The translations of the notification category's title.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification, this can only be "title" or "body".
translations.id UUID	The translation's id.
translations.version integer	The translation's version.

Create notification

POST /content/notifications/

# Create notification
curl -X POST "https://cloudmc_endpoint/v2/rest/content/notifications/" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
    "translations": [
        {
            "language": "en",
            "text": "system-notification-create-no-author",
            "type": "title"
        },
        {
            "language": "fr",
            "text": "en français",
            "type": "title"
        },
        {
            "language": "en",
            "text": "system notification create",
            "type": "body"
        },
        {
            "language": "fr",
            "text": "en français",
            "type": "body"
        }
    ],
    "category": {
        "id": "2569f2cc-f1d7-4664-8439-173fedfab1c3"
    }
}

Create a notification.

Required
category Notification Category]	The notification category that the notification belongs to. includes: id
translations Array[Object]	The translations of the notification category's content.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification, this can only be "title" or "body".

Optional
publishedAt string	The date on which the notification has been/will be published.
deprecatedAt string	The date on which the notification has been/will be deprecated.
splash boolean	When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true.
sticky boolean	When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true.

Update notification

PUT /content/notifications/:id

# Update notification
curl -X PUT "https://cloudmc_endpoint/v2/rest/content/notifications/:id" \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
    "id":"e5412e1d-64ac-40b2-a1a1-05780584fc71",
    "translations": [
        {
            "language": "en",
            "text": "system-notification-create-no-autho",
            "type": "title"
        },
        {
            "language": "fr",
            "text": "en français",
            "type": "title"
        },
        {
            "language": "en",
            "text": "system notification create",
            "type": "body"
        },
        {
            "language": "fr",
            "text": "en français",
            "type": "body"
        }
    ],
    "category": {
        "id": "dc921a2a-16c2-4bc3-8ed6-bcb571bae241"
    }
}

Update a notification.

Required
id UUID	The id of the notification.
category Notification Category]	The notification category that the notification belongs to. includes: id
translations Array[Object]	The translations of the notification category's content.
translations.language string	The language of the translation.
translations.text string	The content of the notification.
translations.type string	The content that we are translating. For a notification, this can only be "title" or "body".

Optional
publishedAt string	The date on which the notification has been/will be published.
deprecatedAt string	The date on which the notification has been/will be deprecated.
splash boolean	When set to true, the notification will be displayed in the home screen until it reaches its deprecated date. Only one of splash and sticky can be set to true.
sticky boolean	When set to true, the notification will be displayed upon logging in. Only one of splash and sticky can be set to true.
translations.id UUID	When specified, the existing translation will be modified. If not provided, a new translation will replace the existing one.

Delete notification

DELETE /content/notifications/:id

# Delete a notification category
curl "https://cloudmc_endpoint/v2/content/notifications/:id" \
   -X DELETE -H "MC-Api-Key: your_api_key"

Delete a notification.

Product Catalogs

The product catalogs determine the product configured for a service type and optionally for specific connections.

List product catalogs

GET /product_catalogs

Retrieves a list of product catalogs configured in the system.

# Retrieve product catalog list
curl "https://cloudmc_endpoint/rest/product_catalogs" \
   -H "MC-Api-Key: your_api_key"
```s
> The above command returns a JSON structured like this:

```json
{
  "data": [
    {
      "mode": "ALL_CONNECTIONS_OF_TYPE",
      "serviceType": "cloudca",
      "connectionIds": [],
      "name": {
        "en": "fgsfdg",
        "fr": "sfdg"
      },
      "changes": [],
      "description": {
        "en": "sdfg",
        "fr": "sdg"
      },
      "id": "5ba5df7c-1e60-4d99-869d-dd3d97826b2e",
      "categories": [
        {
          "name": {
            "en": "sdfg",
            "fr": "sdfg"
          },
          "id": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
        }
      ],
      "products": [
        {
          "metricType": "GAUGE",
          "unit": {
            "unit": "HOUR",
            "name": {}
          },
          "period": "HOUR",
          "deprecated": false,
          "name": {
            "en": "vCPU",
            "fr": "vCPU"
          },
          "transformer": {
            "type": "PROPORTIONAL_TO_TIME"
          },
          "id": "342f0d9b-3c3c-456d-b853-31d713b79e72",
          "attribute": "RAWUSAGE",
          "source": "1",
          "filters": [],
          "sku": "vCPU",
          "categoryId": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
        }
      ]
    }
  ]
}

Attributes
id UUID	The UUID of the product catalog.
name Object	The name object in each language for the product catalog.
description string	The description object in each language for the product catalog.
mode string	Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS.
serviceType Object	The service connection type the product catalog is bound to.
connectionIds Array[UUID]	Array of UUID for the service connections that the catalog is bound to.
changes Array[Object]	Array of all changes done on the product catalog.
categories Array[Object]	The list of product categories object.
categories.id UUID	The id of product category object.
categories.name Object	The name object in each language for the category.
products Array[Object]	The list of products assigned to the catalog.
products.metricType string	The type of metrics taken. Possible values: COUNTER, GAUGE.
products.unit Object	The unit object of the product.
products.unit.unit string	The unit value of the product.
products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
products.period string	The period for the product capture. Possible values: HOURS, MONTH.
products.deprecated boolean	Whether or not the product is deprecated. Defaults to false.
products.name Object	The name object in each language for the product name.
products.transformer Object	The object representing the transformation to do on the product usage.
products.transformer.type string	The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE.
products.transformer.expression string	The transformation expression to apply. Only required if the type is EXPRESSION.
products.id UUID	The ID of the product.
products.attribute string	The attribute that will be used to compute usage from the service type usage.
products.source strubg	The source of the usage to get from the service type.
products.filters Array[Object]	The list of products assigned to the catalog.
products.filters.type string	The type of the filter. Possible values: EXPRESSION, SIMPLE.
products.filters.expression string	The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL).
products.filters.field string	The field to filter. This is only required when type is SIMPLE.
products.filters.operator string	The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN.
products.filters.value string	The value to use in the field combined with the operation. This is only required when type is SIMPLE.
products.sku string	The SKU of the product.
products.categoryId UUID	The UUID of the category to which belongs the product.

Retrieve a product catalog

GET /product_catalogs/:id

Retrieve a product catalog's details.

# Retrieve a product catalog's details
curl "https://cloudmc_endpoint/rest/product_catalogs/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "mode": "ALL_CONNECTIONS_OF_TYPE",
    "serviceType": "cloudca",
    "connectionIds": [],
    "name": {
      "en": "fgsfdg",
      "fr": "sfdg"
    },
    "changes": [],
    "description": {
      "en": "sdfg",
      "fr": "sdg"
    },
    "id": "5ba5df7c-1e60-4d99-869d-dd3d97826b2e",
    "categories": [
      {
        "name": {
          "en": "sdfg",
          "fr": "sdfg"
        },
        "id": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
      }
    ],
    "products": [
      {
        "metricType": "GAUGE",
        "unit": {
          "unit": "HOUR",
          "name": {}
        },
        "period": "HOUR",
        "deprecated": false,
        "name": {
          "en": "vCPU",
          "fr": "vCPU"
        },
        "transformer": {
          "type": "PROPORTIONAL_TO_TIME"
        },
        "id": "342f0d9b-3c3c-456d-b853-31d713b79e72",
        "attribute": "RAWUSAGE",
        "source": "1",
        "filters": [],
        "sku": "vCPU",
        "categoryId": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
      }
    ]
  }
}

Attributes
id UUID	The UUID of the product catalog.
name Object	The name object in each language for the product catalog.
description string	The description object in each language for the product catalog.
mode string	Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS.
serviceType Object	The service connection type the product catalog is bound to.
connectionIds Array[UUID]	Array of UUID for the service connections that the catalog is bound to.
changes Array[Object]	Array of all changes done on the product catalog.
categories Array[Object]	The list of product categories object.
categories.id UUID	The id of product category object.
categories.name Object	The name object in each language for the category.
products Array[Object]	The list of products assigned to the catalog.
products.metricType string	The type of metrics taken. Possible values: COUNTER, GAUGE.
products.unit Object	The unit object of the product.
products.unit.unit string	The unit value of the product.
products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
products.period string	The period for the product capture. Possible values: HOURS, MONTH.
products.deprecated boolean	Whether or not the product is deprecated. Deprecated products may not be updated or undeprecated. Defaults to false.
products.name Object	The name object in each language for the product name.
products.transformer Object	The object representing the transformation to do on the product usage.
products.transformer.type string	The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE.
products.transformer.expression string	The transformation expression to apply. Only required if the type is EXPRESSION.
products.id UUID	The ID of the product.
products.attribute string	The attribute that will be used to compute usage from the service type usage.
products.source strubg	The source of the usage to get from the service type.
products.filters Array[Object]	The list of products assigned to the catalog.
products.filters.type string	The type of the filter. Possible values: EXPRESSION, SIMPLE.
products.filters.expression string	The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL).
products.filters.field string	The field to filter. This is only required when type is SIMPLE.
products.filters.operator string	The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN.
products.filters.value string	The value to use in the field combined with the operation. This is only required when type is SIMPLE.
products.sku string	The SKU of the product.
products.categoryId UUID	The UUID of the category to which belongs the product.

Create product catalog

POST /product_catalogs

Create a new product catalog.

# Creates a new product catalog
curl -X POST "https://cloudmc_endpoint/rest/product_catalogs" \
   -H "MC-Api-Key: your_api_key"

Request body example:

 {
      "mode": "ALL_CONNECTIONS_OF_TYPE",
      "serviceType": "cloudca",
      "connectionIds": [],
      "name": {
        "en": "name_en",
        "fr": "name_fr",
        "es": "name_es"
      },
      "description": {
        "en": "beep boop",
        "fr": "beep boop",
        "es": "beep boop"
      },
      "categories": [
        {
          "name": {
            "en": "category_en",
            "fr": "category_fr",
            "es": "category_es"
          },
     "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
        }
      ],
      "products": [
        {
     "categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
          "metricType": "GAUGE",
          "unit": {
            "unit": "HOUR",
            "name": {}
          },
          "period": "HOUR",
          "deprecated": false,
          "name": {
            "en": "product_en",
            "fr": "product_fr",
            "es": "product_es"
          },
          "transformer": {
            "type": "PROPORTIONAL_TO_TIME"
          },
          "attribute": "RAWUSAGE",
          "source": "1",
          "filters": [],
          "sku": "product_sku"
        }
      ]
    }

The above command return JSON structured like this:

{
  "data": {
    "mode": "ALL_CONNECTIONS_OF_TYPE",
    "serviceType": "cloudca",
    "connectionIds": [],
    "name": {
      "en": "madeInApi",
      "fr": "madeInApi",
      "es": "madeInApi"
    },
    "description": {
      "en": "beep boop",
      "fr": "beep boop",
      "es": "beep boop"
    },
    "id": "b541a90b-afb6-44cf-8a0d-3332668bbe12",
    "categories": [
      {
        "name": {
          "en": "category_en",
          "fr": "category_fr",
          "es": "category_es"
        },
        "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
      }
    ],
    "products": [
      {
        "metricType": "GAUGE",
        "unit": {
          "unit": "HOUR",
          "name": {}
        },
        "period": "HOUR",
        "deprecated": false,
        "name": {
          "en": "product_en",
          "fr": "product_fr",
          "es": "product_es"
        },
        "transformer": {
          "type": "PROPORTIONAL_TO_TIME"
        },
        "id": "e28f7a0a-ca4d-4840-af11-ac760bfcd42b",
        "attribute": "RAWUSAGE",
        "source": "1",
        "filters": [],
        "sku": "product_sku",
        "categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
      }
    ]
  }
}

Required
name Object	The name object in each language for the product catalog.
description string	The description object in each language for the product catalog.
mode string	Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS.
serviceType Object	The service connection type the product catalog is bound to.

Optional
connectionIds Array[UUID]	Array of UUID for the service connections that the catalog is bound to.
categories Array[Object]	The list of product categories object.
categories.id UUID	The id of product category object. Required for each category object.
categories.name Object	The name object in each language for the category.
products Array[Object]	The list of products assigned to the catalog.
products.metricType string	The type of metrics taken. Possible values: COUNTER, GAUGE.
products.unit Object	The unit object of the product.
products.unit.unit string	The unit value of the product.
products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
products.period string	The period for the product capture. Possible values: HOURS, MONTH.
products.deprecated boolean	Whether or not the product is deprecated. Deprecated products may not be updated or undeprecated. Defaults to false.
products.name Object	The name object in each language for the product name.
products.transformer Object	The object representing the transformation to do on the product usage.
products.transformer.type string	The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE.
products.transformer.expression string	The transformation expression to apply. Only required if the type is EXPRESSION.
products.id UUID	The id of the product. Returned with the response.
products.attribute string	The source attribute that will be used to compute usage from the service type usage.
products.source strubg	The source of the usage to get from the service type.
products.filters Array[Object]	The list of products assigned to the catalog.
products.filters.type string	The type of the filter. Possible values: EXPRESSION, SIMPLE.
products.filters.expression string	The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL).
products.filters.field string	The field to filter. This is only required when type is SIMPLE.
products.filters.operator string	The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN.
products.filters.value string	The value to use in the field combined with the operation. This is only required when type is SIMPLE.
products.sku string	The SKU of the product.
products.categoryId UUID	The UUID of the category to which belongs the product. Required for each product.

Update product catalog

PUT /product_catalogs/:id

Update an existing product catalog, including its associated categories and products.

The catalog's service type as well as the existing product SKUs cannot be edited. In addition, users may not delete categories or products. Products may be marked as deprecated. Deprecated products may not be updated or un-deprecated.

Changing a product definition affects how future usage charges will be calculated to customers. It will not be retroactively applied to records already processed. A manual rollback can be used to reprocess past usage charges with the updated product definition.

# Updates a product catalog
curl -X PUT "https://cloudmc_endpoint/rest/product_catalogs/b541a90b-afb6-44cf-8a0d-3332668bbe12" \
   -H "MC-Api-Key: your_api_key"

Request body example:

 {
      "mode": "ALL_CONNECTIONS_OF_TYPE",
      "connectionIds": [],
      "name": {
        "en": "updated_en",
        "fr": "name_fr",
        "es": "name_es"
      },
      "description": {
        "en": "beep boop",
        "fr": "beep boop",
        "es": "beep boop"
      },
      "id": "b541a90b-afb6-44cf-8a0d-3332668bbe12",
      "categories": [
        {
          "name": {
            "en": "category_en",
            "fr": "category_fr",
            "es": "category_es"
          },
     "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
        }
      ],
      "products": [
        {
     "categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
          "metricType": "GAUGE",
          "unit": {
            "unit": "HOUR",
            "name": {}
          },
          "period": "HOUR",
          "deprecated": false,
          "name": {
            "en": "product_en",
            "fr": "product_fr",
            "es": "product_es"
          },
          "transformer": {
            "type": "PROPORTIONAL_TO_TIME"
          },
          "id": "e28f7a0a-ca4d-4840-af11-ac760bfcd42b",
          "attribute": "RAWUSAGE",
          "source": "1",
          "filters": [],
        }
      ]
    }

The above command return JSON structured like this:

{
  "data": {
    "mode": "ALL_CONNECTIONS_OF_TYPE",
    "serviceType": "cloudca",
    "connectionIds": [],
    "name": {
      "en": "updated_en",
      "fr": "name_fr",
      "es": "name_es"
    },
    "description": {
      "en": "beep boop",
      "fr": "beep boop",
      "es": "beep boop"
    },
    "id": "b541a90b-afb6-44cf-8a0d-3332668bbe12",
    "categories": [
      {
        "name": {
          "en": "category_en",
          "fr": "category_fr",
          "es": "category_es"
        },
        "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
      }
    ],
    "products": [
      {
        "metricType": "GAUGE",
        "unit": {
          "unit": "HOUR",
          "name": {}
        },
        "period": "HOUR",
        "deprecated": false,
        "name": {
          "en": "product_en",
          "fr": "product_fr",
          "es": "product_es"
        },
        "transformer": {
          "type": "PROPORTIONAL_TO_TIME"
        },
        "id": "e28f7a0a-ca4d-4840-af11-ac760bfcd42b",
        "attribute": "RAWUSAGE",
        "source": "1",
        "filters": [],
        "sku": "product_sku",
        "categoryId": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
      }
    ]
  }
}

Required
name Object	The name object in each language for the product catalog.
description string	The description object in each language for the product catalog.
mode string	Identify the mode if it is for all service type or specific connections. Possible values: ALL_CONNECTIONS_OF_TYPE, SPECIFIC_CONNECTIONS.
categories Array[Object]	The list of product categories object.
categories.id UUID	The id of product category object. Required for each category object.
categories.name Object	The name object in each language for the category.
products Array[Object]	The list of products assigned to the catalog.
products.metricType string	The type of metrics taken. Possible values: COUNTER, GAUGE.
products.unit Object	The unit object of the product.
products.unit.unit string	The unit value of the product.
products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
products.period string	The period for the product capture. Possible values: HOURS, MONTH.
products.name Object	The name object in each language for the product name.
products.deprecated boolean	Whether or not the product is deprecated. Deprecated products may not be updated or undeprecated. Defaults to false.
products.transformer Object	The object representing the transformation to do on the product usage.
products.transformer.type string	The type of transformation to apply. Possible values: PROPORTIONAL_TO_TIME, EXPRESSION, NONE.
products.transformer.expression string	The transformation expression to apply. Only required if the type is EXPRESSION.
products.id UUID	The ID of the product.
products.attribute string	The attribute that will be used to compute usage from the service type usage.
products.source strubg	The source of the usage to get from the service type.
products.filters Array[Object]	The list of products assigned to the catalog.
products.filters.type string	The type of the filter. Possible values: EXPRESSION, SIMPLE.
products.filters.expression string	The expression to filter the product in the usage generation. Only required when the type is EXPRESSION. The expression must follow the syntax of Spring Expression Language(SPEL).
products.filters.field string	The field to filter. This is only required when type is SIMPLE.
products.filters.operator string	The operation to check on the selected field. This is only required when type is SIMPLE. Possible values: EQUAL, NOT_EQUAL, CONTAINS, STARTS_WITH, ENDS_WITH, MATCHES_REGEX, LESS_THAN, LESS_OR_EQUAL_THAN, BIGGER_THAN, BIGGER_OR_EQUAL_THAN.
products.filters.value string	The value to use in the field combined with the operation. This is only required when type is SIMPLE.
products.sku string	The SKU of the product. May not be edited after product is created.
products.categoryId UUID	The UUID of the category to which belongs the product. Required for each product.

Optional
connectionIds Array[UUID]	Array of UUID for the service connections that the catalog is bound to.

Delete product catalog

DELETE /product_catalogs/:id

Delete an existing product catalog. Users may not delete a product catalog that has associated pricings.

# Deletes a specified product catalog
curl -X DELETE "https://cloudmc_endpoint/rest/product_catalogs/b541a90b-afb6-44cf-8a0d-3332668bbe12" \
   -H "MC-Api-Key: your_api_key"

The above command(s) return(s) JSON structured like this:

{
  "taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
  "taskStatus": "SUCCESS"
}

Attributes
taskId string	The task id related to the identity provider deletion.
taskStatus string	The status of the operation.

Pricings

The pricing determines the price for each product defined for a selected catalog.

List pricings

GET /pricings

Retrieves a list of pricings configured in the system.

# Retrieve pricing list
curl "https://cloudmc_endpoint/rest/pricings" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "supportedCurrencies": [
        "CAD"
      ],
      "productCatalogs": [
        {
          "mode": "ALL_CONNECTIONS_OF_TYPE",
          "serviceType": "cloudca",
          "connectionIds": [],
          "name": {
            "en": "Default cloud.ca",
            "fr": "Défaut cloud.ca"
          },
          "description": {
            "en": "cloud.ca default product catalog",
            "fr": "catalogue des produits cloud.ca par défaut"
          },
          "id": "5ba5df7c-1e60-4d99-869d-dd3d97826b2e"
        },
      ],
      "organization": {
        "id": "409c1162-a930-4207-bdf9-710580c3542b"
      },
      "pricingProducts": [
        {
          "unitPrice": 123.0,
          "product": {
            "metricType": "GAUGE",
            "unit": {
              "unit": "HOUR",
              "name": {}
            },
            "period": "HOUR",
            "name": {
              "en": "vCPU",
              "fr": "vCPU"
            },
            "transformer": {
              "type": "PROPORTIONAL_TO_TIME"
            },
            "id": "342f0d9b-3c3c-456d-b853-31d713b79e72",
            "attribute": "RAWUSAGE",
            "source": "1",
            "filters": [],
            "sku": "vCPU",
            "categoryId": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
          },
          "pricingTiers": [
            {
              "pricingMode": "FLAT_FEE",
              "lowerBound": 0.0,
              "upperBound": 1000.5,
              "price": {
                "CAD": 999
              },
              "id": "9c560c79-e600-4a8b-b73b-d359a6512601"
             },
             {
              "pricingMode": "FLAT_FEE",
              "lowerBound": 1000.5,
              "chunkSize": 500,
              "price": {
                "CAD": 999
              },
              "id": "accf0b65-1406-45d6-b6d8-b83c062efcd7"
             }
           ],
          "cogs": 321.0,
          "currency": "CAD",
          "id": "45425fe6-beb3-4c78-be68-f82eeb3976c6"
        }
      ],
      "name": {
        "en": "cloud.ca default pricing",
        "fr": "prix par défaut cloud.ca"
      },
      "description": {
        "en": "cloud.ca default pricing",
        "fr": "prix par défaut cloud.ca"
      },
      "id": "096bbfee-a6e6-4373-8a4e-1a8b0f2bf484",
      "effectiveDate": "2020-05-08T16:53:45Z"
    }
  ]
}

Attributes
id UUID	The UUID of the pricing.
name Object	The name object in each language for the pricing.
description string	The description object in each language for the pricing.
supportedCurrencies Array[string]	List of the currencies which are supported by this pricing.
productCatalogs Array[Object]	List of product catalog objects which are attached to this pricing.
organization.id UUID	UUID of the organisation to which belongs the pricing.
pricingProducts Array[Object]	The list of product pricings assigned to the pricing.
pricingProducts.id UUID	UUID of the product pricing.
pricingProducts.unitPrice double	The unit price of the product.
pricingProducts.product Object	The product attached to this product pricing element.
pricingProducts.cogs double	The Cost Of Goods Sold (COGS) of the product.
pricingProducts.currency string	The currency of the pricing.
pricingProducts.pricingTiers Array[Object]	The list of pricing tiers assigned to the product pricings.
pricingProducts.pricingTier.id UUID	UUID of the pricing tier.
pricingProducts.pricingTier.pricingMode Enum	The pricing mode of the pricing tier. Must be one of "FLAT_FEE" or "PER_UNIT".
pricingProducts.pricingTier.lowerBound double	The pricing tier's lower bound.
pricingProducts.pricingTier.upperBound double	The pricing tier's upper bound. A null value indicates that there is no upper bound for the given tier.
pricingProducts.pricingTier.price Map[string, double]>	The pricing tier's price in each of the pricing product's supported currencies.
pricingProducts.pricingTier.chunkSize double	The pricing tier's chunk size.

Retrieve a pricing

GET /pricings/:id

Retrieve a pricing's details.

# Retrieve a pricing's details
curl "https://cloudmc_endpoint/rest/pricings/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "supportedCurrencies": [
      "CAD"
    ],
    "productCatalogs": [
      {
        "mode": "ALL_CONNECTIONS_OF_TYPE",
        "serviceType": "cloudca",
        "connectionIds": [],
        "name": {
          "en": "Default cloud.ca",
          "fr": "Défaut cloud.ca"
        },
        "changes": [],
         "description": {
          "en": "cloud.ca default product catalog",
          "fr": "catalogue des produits cloud.ca par défaut"
        },
        "id": "5ba5df7c-1e60-4d99-869d-dd3d97826b2e",
        "categories": [
          {
            "name": {
              "en": "Compute",
              "fr": "Compute"
            },
            "id": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
          }
        ],
        "products": [
          {
            "metricType": "GAUGE",
            "unit": {
              "unit": "HOUR",
              "name": {}
            },
            "period": "HOUR",
            "name": {
              "en": "vCPU",
              "fr": "vCPU"
            },
            "transformer": {
              "type": "PROPORTIONAL_TO_TIME"
            },
            "id": "342f0d9b-3c3c-456d-b853-31d713b79e72",
            "attribute": "RAWUSAGE",
            "source": "1",
            "filters": [],
            "sku": "vCPU",
            "categoryId": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
          }
        ]
      }
    ],
    "organization": {
      "id": "409c1162-a930-4207-bdf9-710580c3542b"
    },
    "pricingProducts": [
      {
        "unitPrice": 123.0,
        "product": {
          "metricType": "GAUGE",
          "unit": {
            "unit": "HOUR",
            "name": {}
          },
          "period": "HOUR",
          "name": {
            "en": "sfg",
            "fr": "sdfg"
          },
          "pricingTiers": [
            {
              "pricingMode": "FLAT_FEE",
              "lowerBound": 0.0,
              "upperBound": 1000.5,
              "price": {
               "CAD": 999
              },
             "id": "9c560c79-e600-4a8b-b73b-d359a6512601"
            },
            {
             "pricingMode": "FLAT_FEE",
             "lowerBound": 1000.5,
             "chunkSize": 500,
             "price": {
              "CAD": 999
             },
             "id": "accf0b65-1406-45d6-b6d8-b83c062efcd7"
            }
           ],
          "transformer": {
            "type": "PROPORTIONAL_TO_TIME"
          },
          "id": "342f0d9b-3c3c-456d-b853-31d713b79e72",
          "attribute": "RAWUSAGE",
          "source": "1",
          "filters": [],
          "sku": "sdfg",
          "categoryId": "fcd8908d-e1a0-41f2-9c38-fed1d1f77f18"
        },
        "cogs": 321.0,
        "currency": "USD",
        "id": "45425fe6-beb3-4c78-be68-f82eeb3976c6"
      }
    ],
    "name": {
      "en": "testen",
      "fr": "testfr"
    },
    "description": {
      "en": "descen",
      "fr": "testfr"
    },
    "id": "096bbfee-a6e6-4373-8a4e-1a8b0f2bf484",
    "effectiveDate": "2020-05-08T16:53:45Z"
  }
}

Attributes
id UUID	The UUID of the pricing.
name Object	The name object in each language for the pricing.
description string	The description object in each language for the pricing.
supportedCurrencies Array[string]	List of the currencies which are supported by this pricing.
productCatalogs Array[Object]	List of product catalog objects which are attached to this pricing.
organization.id UUID	UUID of the organisation to which belongs the pricing. It is more detailed.
pricingProducts Array[Object]	The list of product pricings assigned to the pricing.
pricingProducts.id UUID	UUID of the product pricing.
pricingProducts.unitPrice double	The unit price of the product.
pricingProducts.product Object	The product attached to this product pricing element.
pricingProducts.cogs double	The Cost Of Goods Sold (COGS) of the product.
pricingProducts.currency string	The currency of the pricing.
pricingProducts.pricingTiers Array[Object]	The list of pricing tiers assigned to the product pricings.
pricingProducts.pricingTier.id UUID	UUID of the pricing tier.
pricingProducts.pricingTier.pricingMode Enum	The pricing mode of the pricing tier. Must be one of "FLAT_FEE" or "PER_UNIT".
pricingProducts.pricingTier.lowerBound double	The pricing tier's lower bound.
pricingProducts.pricingTier.upperBound double	The pricing tier's upper bound. A null value indicates that there is no upper bound for the given tier.
pricingProducts.pricingTier.price Map[string, double]>	The pricing tier's price in each of the pricing product's supported currencies.
pricingProducts.pricingTier.chunkSize double	The pricing tier's chunk size.

Create pricing

POST /pricings

Create a new pricing.

# Creates a new pricing
curl -X POST "https://cloudmc_endpoint/rest/pricings" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
    "organization": {
        "id": "1d37a999-6ac6-4193-acb2-49df5c43ff31"
    },
    "productCatalogs": [
        {
            "id": "b6c89a59-34bf-4be4-a9bf-4414de84f5f7"
        }
    ],
    "name": {
        "en": "name",
        "fr": "nom",
        "es": "nombre"
    },
    "description": {
        "en": "desc_en",
        "fr": "desc_fr",
        "es": "desc_es"
    },
    "effectiveDate": "2020-05-06T00:00:00.000Z",
    "pricingProducts": [
        {
            "product": {
                "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
            },
            "cogs": 4,
            "unitPrice": 5,
            "currency": "CAD",
      "pricingTiers": [
        {
         "pricingMode": "FLAT_FEE",
         "lowerBound": 0.0,
         "upperBound": 1000.5,
         "price": {
         "CAD": 999
         },
         "id": "9c560c79-e600-4a8b-b73b-d359a6512601"
        },
        {
         "pricingMode": "FLAT_FEE",
         "lowerBound": 1000.5,
         "chunkSize": 500,
         "price": {
          "CAD": 999
         },
         "id": "accf0b65-1406-45d6-b6d8-b83c062efcd7"
        }
      ],
        },
        {
            "product": {
                "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
            },
            "cogs": 4,
            "unitPrice": 5,
            "currency": "USD"
        }
    ],
    "supportedCurrencies": [
        "CAD",
        "USD"
    ]
}

The above command return JSON structured like this:

{
  "data": {
    "supportedCurrencies": [
      "CAD",
      "USD"
    ],
    "productCatalogs": [
      {
        "id": "b6c89a59-34bf-4be4-a9bf-4414de84f5f7"
      }
    ],
    "organization": {
      "id": "1d37a999-6ac6-4193-acb2-49df5c43ff31"
    },
    "pricingProducts": [
      {
        "unitPrice": 5,
        "product": {
          "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
        },
        "cogs": 4,
        "currency": "CAD",
        "id": "45301951-59cb-461e-b0d0-85c46a7abb69",
        "pricingProducts": [
        {
            "product": {
                "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3"
            },
            "cogs": 4,
            "unitPrice": 5,
            "currency": "CAD",
      "pricingTiers": [
        {
         "pricingMode": "FLAT_FEE",
         "lowerBound": 0.0,
         "upperBound": 1000.5,
         "price": {
         "CAD": 999
         },
         "id": "9c560c79-e600-4a8b-b73b-d359a6512601"
        },
        {
         "pricingMode": "FLAT_FEE",
         "lowerBound": 1000.5,
         "chunkSize": 500,
         "price": {
          "CAD": 999
         },
         "id": "accf0b65-1406-45d6-b6d8-b83c062efcd7"
        }
      ]
      },
      {
        "unitPrice": 5,
        "product": {
          "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
        },
        "cogs": 4,
        "currency": "USD",
        "id": "30ec5361-0044-44d5-a8b1-68dca07d274e"
      }
    ],
    "name": {
      "en": "name",
      "fr": "nom",
      "es": "nombre"
    },
    "changes": [],
    "description": {
      "en": "desc_en",
      "fr": "desc_fr",
      "es": "desc_es"
    },
    "id": "c4860b7d-ad41-40a8-b2a2-6f96be87c8b0",
    "effectiveDate": "2020-05-06T00:00:00Z"
  }
}

Required
organization.id UUID	The id of the organization the pricing belongs to.
productCatalogs Array[productCatalogs.id]	An array of product catalogs the pricing can add products from.
productCatalogs.id UUID	The id for a product catalog you'd like to add as a source for your pricing.
name Object	A map of language keys to a name in the specified language.
effectiveDate string	The date the pricing should become effective.
pricingProducts Array[pricingProduct]	A list of products from a supplied product catalog that are priced, need to supply a product with every supported currency.
pricingProduct.product.id UUID	The id of the product you're applying a price to. Must be contained in one of the specified product catalogs.
pricingProduct.cogs int	The cost of goods sold, represents the direct cost of producing the specified product.
pricingProduct.unitPrice int	The unit price is the price at which the product will be sold to the consumer.
pricingProduct.currency string	The currency the price is set in.
supportedCurrencies Array[string]	An array of supported currencies.

Optional
description Object	A map of language language keys to the description in the specified language.
pricingProducts.pricingTiers Array[Object]	The list of pricing tiers assigned to the product pricings. Pricing tiers must be contiguous, there cannot be any overlap between tiers, nor can there be gaps in between them.
pricingProducts.pricingTier.pricingMode Enum	The pricing mode of the pricing tier. Must be one of "FLAT_FEE" or "PER_UNIT". If a pricing tier is specified, this attribute is mandatory.
pricingProducts.pricingTier.lowerBound double	The pricing tier's lower bound. The lower bound must be a non-negative value. If a pricing tier is specified, this attribute is mandatory.
pricingProducts.pricingTier.upperBound double	The pricing tier's upper bound. The upper bound must be a non-negative value. If a pricing tier is specified, the upper bound must be specified unless it is a part of the last pricing tier. In that case, a null value indicates that there is no upper bound for the given tier.
pricingProducts.pricingTier.price Map[string, double]>	The pricing tier's price in each of the pricing product's supported currencies. All currencies specified must be supported by the pricing. Any missing or invalid currencies will not be accepted. Also, pricings must be non-negative.
pricingProducts.pricingTier.chunkSize double	The pricing tier's chunk size. The chunk size must be a non-negative value

Update pricing

PUT /pricings/:id

Update an existing pricing's name and description.

# Creates a new pricing
curl -X PUT "https://cloudmc_endpoint/rest/pricings/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": {
      "en": "name-updated",
      "fr": "nom-updated",
      "es": "nombre-updated"
  },
  "description": {
    "en": "pricing-desc-updated",
    "fr": "desc_fr",
    "es": "desc_es"
  }
}

The above command return JSON structured like this:

{
  "data": {
    "supportedCurrencies": [
      "CAD",
      "USD"
    ],
    "productCatalogs": [
      {
        "id": "b6c89a59-34bf-4be4-a9bf-4414de84f5f7"
      }
    ],
    "organization": {
      "id": "1d37a999-6ac6-4193-acb2-49df5c43ff31"
    },
    "pricingProducts": [
      {
        "unitPrice": 5,
        "product": {
          "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
        },
        "cogs": 4,
        "currency": "CAD",
        "id": "45301951-59cb-461e-b0d0-85c46a7abb69"
      },
      {
        "unitPrice": 5,
        "product": {
          "id": "c14daee2-4678-4710-b9af-fc26fbd3c7f3",
        },
        "cogs": 4,
        "currency": "USD",
        "id": "30ec5361-0044-44d5-a8b1-68dca07d274e"
      }
    ],
    "name": {
      "en": "name-updated",
      "fr": "nom-updated",
      "es": "nombre-updated"
    },
    "changes": [],
    "description": {
      "en": "pricing-desc-updated",
      "fr": "desc_fr",
      "es": "desc_es"
    },
    "id": "03bc22bd-adc4-46b8-988d-afddc24c0cb5",
    "effectiveDate": "2020-05-06T00:00:00Z"
  }
}

Required
name Object	A map of language keys to a name in the specified language.

Optional
description Object	A map of language language keys to the description in the specified language.

Delete pricing

DELETE /pricings/:id

Delete an existing pricing. A pricing cannot be deleted if it is associated to an applied pricing.

curl -X DELETE "https://cloudmc_endpoint/rest/pricings/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
  "taskStatus": "SUCCESS"
}

Applied Pricings

The applied pricing allows the assignment of pricing to organization with a determined scope.

List applied pricings

GET /applied_pricings

Retrieves a list of applied pricings configured in the system.

# Retrieve applied pricing list
curl "https://cloudmc_endpoint/rest/applied_pricings" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "pricingDefinition": {
        "supportedCurrencies": [
          "CAD",
          "USD"
        ],
        "organization": {
          "id": "23910576-d29f-4c14-b663-31d728ff49a5"
        },
        "name": {
          "en": "Simple pricing",
          "fr": "Facturaction simple"
        },
        "changes": [],
        "description": {},
        "id": "f786b9c5-177b-4cbc-9011-331282485d05",
        "effectiveDate": "2020-06-04T17:55:17Z"
      },
      "endDate": "2021-06-05T23:59:59.999Z",
      "organization": {
        "name": "System",
        "id": "23910576-d29f-4c14-b663-31d728ff49a5"
      },
      "currency": "USD",
      "id": "47c4993a-a131-4365-a427-02de95bad85b",
      "creationDate": "2020-06-04T18:30:21.000Z",
      "scopeQualifier": "GLOBAL",
      "startDate": "2020-06-05T00:00:00Z",
      "status": "ACTIVE"
    }
  ]
}

Attributes
id UUID	The UUID of the applied pricing.
pricingDefinition Object	The pricing definition associated with the applied pricing.
pricingDefinition.id UUID	The UUID of the pricing.
pricingDefinition.supportedCurrencies Array[string]	The list of currencies associated to the pricing.
pricingDefinition.organization.id UUID	The UUID of the organization owning of the pricing definition.
pricingDefinition.name Object	Mapped object containing the pricing name in different languages.
pricingDefinition.description Object	Mapped object containing the pricing description in different languages.
pricingDefinition.effectiveDate date	The date to which the pricing will be applicable from.
organization Object	The object representing the organization owning the applied pricing.
organization.id UUID	The UUID of the organization.
organization.name string	The name of the organization.
startDate date	The start date of the applied pricing.
endDate date	The end date of the applied pricing. If it is not present, there is no end date defined.
currency string	The currency associated to the applied pricing.
scopeQualifier string	Scope qualifier of the applied pricing. Possible values are : GLOBAL, ORG_TOPLEVEL, ORG_SUBS, ORG_BASE, ORG_TREE.
scopeOrganization Object	The organization to which the scope is applied to.
scopeOrganization.id UUID	The UUID of the organization.
scopeOrganization.name string	The name of the organization.
creationDate Object	The date the applied pricing was created.
status string	The status of the applied pricing. Possible values are : ACTIVE, EXPIRED, FUTURE.

Retrieve an applied pricing

GET /applied_pricings/:id

Retrieve an applied pricing's details.

# Retrieve an applied pricing
curl "https://cloudmc_endpoint/rest/applied_pricings/03bc22bd-adc4-46b8-988d-afddc24c0cb5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "pricingDefinition": {
      "supportedCurrencies": [
        "CAD",
        "USD"
      ],
      "organization": {
        "id": "23910576-d29f-4c14-b663-31d728ff49a5"
      },
      "name": {
        "en": "Simple pricing",
        "fr": "Facturaction simple"
      },
      "changes": [],
      "description": {},
      "id": "f786b9c5-177b-4cbc-9011-331282485d05",
      "effectiveDate": "2020-06-04T17:55:17Z"
    },
    "endDate": "2021-06-05T23:59:59.999Z",
    "organization": {
      "name": "System",
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "currency": "USD",
    "id": "47c4993a-a131-4365-a427-02de95bad85b",
    "creationDate": "2020-06-04T18:30:21.000Z",
    "scopeQualifier": "GLOBAL",
    "startDate": "2020-06-05T00:00:00Z",
    "status": "ACTIVE"
  }
}

Attributes
id UUID	The UUID of the applied pricing.
pricingDefinition Object	The pricing definition associated with the applied pricing.
pricingDefinition.id UUID	The UUID of the pricing.
pricingDefinition.supportedCurrencies Array[string]	The list of currencies associated to the pricing.
pricingDefinition.organization.id UUID	The UUID of the organization owning of the pricing definition.
pricingDefinition.name Object	Mapped object containing the pricing name in different languages.
pricingDefinition.description Object	Mapped object containing the pricing description in different languages.
pricingDefinition.effectiveDate date	The date to which the pricing will be applicable from.
organization Object	The object representing the organization owning the applied pricing.
organization.id UUID	The UUID of the organization.
organization.name string	The name of the organization.
startDate date	The start date of the applied pricing.
endDate date	The end date of the applied pricing. If it is not present, there is no end date defined.
currency string	The currency associated to the applied pricing.
scopeQualifier string	Scope qualifier of the applied pricing. Possible values are : GLOBAL, ORG_TOPLEVEL, ORG_SUBS, ORG_BASE, ORG_TREE.
scopeOrganization Object	The organization to which the scope is applied to.
scopeOrganization.id UUID	The UUID of the organization.
scopeOrganization.name string	The name of the organization.
creationDate Object	The date the applied pricing was created.
status string	The status of the applied pricing. Possible values are : ACTIVE, EXPIRED, FUTURE.

Create applied pricing

POST /applied_pricings

Create a new applied pricing.

# Creates a new pricing
curl -X POST "https://cloudmc_endpoint/rest/applied_pricings" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "pricingDefinition": {
    "id": "f786b9c5-177b-4cbc-9011-331282485d05"
  },
  "organization": {
    "id": "23910576-d29f-4c14-b663-31d728ff49a5"
  },
  "currency": "USD",
  "scopeQualifier": "GLOBAL",
  "startDate": "2020-06-05T00:00:00Z",
  "endDate": "2021-06-05T23:59:59.999Z"
}

The above command return JSON structured like this:

{
  "data": {
    "pricingDefinition": {
      "name": {},
      "changes": [],
      "description": {},
      "id": "f786b9c5-177b-4cbc-9011-331282485d05"
    },
    "endDate": "2021-06-05T23:59:59.999Z",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "currency": "USD",
    "id": "8bb5e457-41c3-410b-aced-b9c694ff141a",
    "creationDate": "2020-06-04T19:31:31.178Z",
    "scopeQualifier": "GLOBAL",
    "startDate": "2020-06-05T00:00:00Z"
  }
}

Required
organization.id UUID	The UUID of the organization the applied pricing belongs to.
pricingDefinition.id UUID	the UUID of the pricing that will be used in the applied pricing.
scopeQualifier string	The scope qualifier for the applied pricing. Possible values are : ORG_BASE, ORG_TREE, ORG_SUB, ORG_TOPLEVEL, GLOBAL.
currency String	The currency used for the applied pricing. The value is a ISO 4217 currency code that is part of the pricing selected.
startDate Date	The start date for the applied pricing.

Optional
endDate Date	The end date for the applied pricing.
scopeOrganization.id UUID	The UUID of the organization that the scope is targeting. Only required for scopes : ORG_BASE, ORG_TREE, ORG_SUBS.

Update applied pricing

PUT /applied_pricings/:id

Update an applied pricing. Updates to the pricing, the scope, start date and end date may cause charges to be rolled back.

# Update an applied pricing
curl -X PUT "https://cloudmc_endpoint/rest/applied_pricings/8bb5e457-41c3-410b-aced-b9c694ff141a" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "pricingDefinition": {
    "id": "f786b9c5-177b-4cbc-9011-331282485d05"
  },
  "organization": {
    "id": "23910576-d29f-4c14-b663-31d728ff49a5"
  },
  "currency": "USD",
  "scopeQualifier": "ORG_BASE",
  "scopeOrganization": {
    "id": "d2e467f8-3a33-441a-b074-aec960758452"
  },
  "startDate": "2020-06-05T00:00:00Z",
  "endDate": "2021-06-05T23:59:59.999Z"
}

The above command return JSON structured like this:

{
  "data": {
    "pricingDefinition": {
      "supportedCurrencies": [
        "CAD",
        "USD"
      ],
      "organization": {
        "id": "23910576-d29f-4c14-b663-31d728ff49a5"
      },
      "name": {
        "en": "my-pricing",
        "fr": "mon-pricing"
      },
      "changes": [],
      "description": {},
      "id": "f786b9c5-177b-4cbc-9011-331282485d05",
      "effectiveDate": "2020-05-06T00:00:00Z"
    },
    "endDate": "2021-06-05T23:59:59.999Z",
    "organization": {
      "name": "Systemer",
      "id": "52fd201e-aa82-4a27-86b3-ea9650a7fb1e"
    },
    "currency": "CAD",
    "id": "d08b9332-d26e-42fe-b272-3071f2d64839",
    "creationDate": "2020-09-08T17:44:18.000Z",
    "scopeQualifier": "ORG_BASE",
    "scopeOrganization": {
      "id": "d2e467f8-3a33-441a-b074-aec960758452",
      "name": "scoped-organization",
    },
    "startDate": "2020-06-05T00:00:00Z"
  }
}

Required
organization.id UUID	The UUID of the organization the applied pricing belongs to.
pricingDefinition.id UUID	the UUID of the pricing that will be used in the applied pricing.
scopeQualifier string	The scope qualifier for the applied pricing. Possible values are : ORG_BASE, ORG_TREE, ORG_SUB, ORG_TOPLEVEL, GLOBAL.
currency String	The currency used for the applied pricing. The value is a ISO 4217 currency code that is part of the pricing selected.
startDate Date	The start date for the applied pricing.

Optional
endDate Date	The end date for the applied pricing.
scopeOrganization.id UUID	The UUID of the organization that the scope is targeting. Only required for scopes : ORG_BASE, ORG_TREE, ORG_SUBS.

Delete applied pricing

DELETE /applied_pricings/:id

Delete an existing applied pricing. Deleting an applied pricing that is ACTIVE or EXPIRED may cause charges to be rolled back.

curl -X DELETE "https://cloudmc_endpoint/rest/applied_pricings/d08b9332-d26e-42fe-b272-3071f2d64839" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
  "taskStatus": "SUCCESS"
}

Rollbacks

Rollbacks enable service providers to reprocess usage data from the past. Currently the only supported rollback type REPROCESS uses existing collected usage metrics and reprocesses it through the monetization engine. The most current effective pricing configuration will be used to price these records.

List rollback triggers

GET /rollbacks

Retrives a list of rollback triggers for a reseller.

Note: You must have the Reseller pricing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a 404 Not Found response will be returned. The organization_id query parameter is optional. If not present, it will default to the caller's organization.

# Retrieve rollback triggers
curl "https://cloudmc_endpoint/rest/rollbacks?organization_id=23910576-d29f-4c14-b663-31d728ff49a5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "createdDate": "2022-01-06T17:43:55Z",
      "resetDate": "2022-01-06",
      "rollbacks": [
        {
          "resetDate": "2022-01-06",
          "organization": {
            "name": "Operator",
            "id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
          },
          "id": 28428,
          "state": "COMPLETED",
          "serviceConnection": {
            "serviceCode": "swiftstack-aaaa",
            "name": "Object Storage",
            "id": "4fa42796-6b93-4d9f-b5f7-34c4d1c796ea",
            "type": "swiftstack"
          }
        },
        {
          "resetDate": "2022-01-06",
          "organization": {
            "name": "WhitePages",
            "id": "5f07f7d6-8eaf-418e-87a1-8dc063135003"
          },
          "id": 28429,
          "state": "SCHEDULED",
          "serviceConnection": {
            "serviceCode": "stackpath-aaaa",
            "name": "Edge Services",
            "id": "2d468fc0-434d-49a7-9739-e8d4fda0c488",
            "type": "stackpath"
          }
        }
      ],
      "organization": {
        "name": "Operator",
        "id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
      },
      "name": "Rollback January",
      "description": "This is a description",
      "id": "006980fe-6ee5-4c04-a0aa-df04acab54f9",
      "state": "SCHEDULED",
      "type": "REPROCESS"
    }
  ]
}

Attributes
id UUID	The UUID of the rollback trigger provider.
name string	The name of the rollback.
description string	The description of the rollback (optional).
organization.id UUID	The UUID of the organization (reseller) responsble for creating the rollback trigger
type string	The type of the rollback: Possible values are REPROCESS, RECOLLECT.
	The REPROCESS type is only available to users with operator permission.
	The RECOLLECT type is available to connection owners and operators.
state enum	The state of the rollback. Possible values are: COMPLETED, SCHEDULED & PENDING.
createdDate string	The date the rollback trigger was created.
resetDate string	The date in which we want to start the rollback (inclusive).
rollbacks Array	A list of rollbacks scoped to a service connection and organization.

Get a rollback trigger

GET /rollbacks/:id

Retrives a rollback trigger's details.

Note: You must have the Reseller pricing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a 404 Not Found response will be returned.

# Retrieve rollback triggers
curl "https://cloudmc_endpoint/rest/rollbacks/23910576-d29f-4c14-b663-31d728ff49a5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "createdDate": "2022-01-10T17:06:10Z",
    "resetDate": "2022-01-10",
    "rollbacks": [
      {
        "resetDate": "2022-01-10",
        "organization": {
          "name": "WhitePages",
          "id": "5f07f7d6-8eaf-418e-87a1-8dc063135003"
        },
        "id": 28446,
        "state": "COMPLETED",
        "serviceConnection": {
          "serviceCode": "swiftstack-aaaa",
          "name": "Object Storage",
          "id": "4fa42796-6b93-4d9f-b5f7-34c4d1c796ea",
          "type": "swiftstack"
        }
      }
    ],
    "organization": {
      "name": "Operator",
      "id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
    },
    "name": "Rollback",
    "description": "Fix bug in pipeline for date conversion",
    "id": "6064e10e-a105-423a-b724-ba470bf42e79",
    "state": "COMPLETED",
    "type": "REPROCESS"
  }
}

Attributes
id UUID	The UUID of the rollback trigger provider.
name string	The name of the rollback.
description string	The description of the rollback (optional).
organization.id UUID	The UUID of the organization (reseller) responsble for creating the rollback trigger.
type string	The type of the rollback: Possible values are REPROCESS, RECOLLECT.
	The REPROCESS type is only available to users with operator permission.
	The RECOLLECT type is available to connection owners and operators.
state enum	The state of the rollback. Possible values are: COMPLETED, SCHEDULED & PENDING.
createdDate string	The date the rollback trigger was created.
resetDate string	The date in which we want to start the rollback (inclusive).
rollbacks Array	A list of rollbacks scoped to a service connection and organization that were generated based on the rollback trigger configuration.

Create a rollback trigger

POST /rollbacks

Creates a rollback which will result in reprocessing of usage for the given request body. The Rollback API supports two types of rollback: REPROCESS and RECOLLECT.

The REPROCESS rollback re-processes existing usage, previously collected from the backend service, in the monetization engine. The latest pricing configuration will be used on these records. The API body supports targeting a set of service connections and organizations as well as the date from which the rollback should begin the reprocess. If usage is not found for the requested date and organization and service connection pair the API will default to the earliest available usage for the pair. If there is no previous usage for the organization and connection, no rollback will be generated for this pair.

The RECOLLECT rollback type can be used by connection owners to retrigger the collection of usage from the underlying backend service. The RECOLLECT rollback is limitted by the retention period of underlying usage of the targeted service. If, for example, the targeted service only stores 60 days of usage the earliest reset date will be 60 days before today. A recollect rollback impacts all assigned organizations of the selected service connection.

Note: this operation will take time and the state of the rollbacks will update once the operation is complete.

Once a rollback is complete the usage on the customer usage reports after the selected reset date should reflect the latest pricing configuration applied. Rollbacks of all types will not impact issued, paid or overdue invoices. Only invoices that are not in the hands of customers will be regenerated.

Note: You must have the Reseller pricing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a 404 Not Found response will be returned.

# Retrieve rollback triggers
curl "https://cloudmc_endpoint/rest/rollbacks/23910576-d29f-4c14-b663-31d728ff49a5" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": "Rollback - Object Storage",
  "description": "This rollback correct API errors from the service",
  "type": "REPROCESS",
  "organization": {
    "id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
  },
  "resetDate": "2022-01-10",
  "serviceConnectionIds": ["4fa42796-6b93-4d9f-b5f7-34c4d1c796ea"],
  "organizationIds": ["5f07f7d6-8eaf-418e-87a1-8dc063135003"]
}

The above command returns a JSON structured like this:

{
  "data": {
    "resetDate": "2022-01-10",
    "rollbacks": [
      {
        "resetDate": "2022-01-10",
        "organization": {
          "name": "WhitePages",
          "id": "5f07f7d6-8eaf-418e-87a1-8dc063135003"
        },
        "id": 28447,
        "state": "SCHEDULED",
        "serviceConnection": {
          "serviceCode": "swiftstack-aaaa",
          "name": "Object Storage",
          "id": "4fa42796-6b93-4d9f-b5f7-34c4d1c796ea",
          "type": "swiftstack"
        }
      }
    ],
    "organization": {
      "id": "1b47df69-6458-4ea6-8c4b-2894b3f7ec00"
    },
    "name": "Rollback - Object Storage",
    "description": "This rollback correct API errors from the service",
    "id": "eb484aea-cf19-4db1-8329-507d8a0d5c17",
    "state": "SCHEDULED",
    "type": "REPROCESS"
  }
}

Attributes
id UUID	The UUID of the rollback trigger provider.
name string	The name of the rollback.
description string	The description of the rollback (optional).
organization.id UUID	The UUID of the organization (reseller) responsble for creating the rollback trigger.
type string	The type of the rollback: Possible values are REPROCESS, RECOLLECT.
	The REPROCESS type is only available to users with operator permission.
	The RECOLLECT type is available to connection owners and operators.
resetDate string	The date in which we want to start the rollback (inclusive).
organizationIds Array	The list of targeted organization IDs to apply the rollback.
serviceConnectionIds Array	The list of affected service connection IDs to apply the rollback.

Invoices

Note: Creating, deleting and updating invoices is not supported.

Get customer invoices by reseller ID

GET /invoices/find/:reseller_id/customer_invoices

Retrieve a list of invoices belonging to the customers of the reseller specified.

# Retrieve customer invoices list
curl "https://cloudmc_endpoint/rest/invoices/find/efd32752-c6f2-45cf-b494-cc6be8a45845/customer_invoices?includeAllSubOrgs=false&billingCycle=07-2021" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "createdDate": "2021-11-22T17:22:49Z",
            "billingCycle": {
                "id": "7c10604c-3045-40ef-9890-1bd5a23d5a7b"
            },
            "organization": {
                "name": "System",
                "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
            },
            "invoiceId": "X5GDVRKGCY",
            "id": "504735ce-cdc1-4adf-b59c-b4e43d1eefa4",
            "detail": {
                "adjustments": [
                    {
                        "amount": -41650.89,
                        "dailyDeltas": {
                            "2021-10-06": 0.0,
                            "2021-10-07": -1352.01792,
                            "2021-10-08": -899.184845,
                            "2021-10-02": -422.4,
                            "2021-10-03": -422.4,
                            "2021-10-04": -686.35776,
                            "2021-10-05": -2015.18592,
                            "2021-09-30": -422.4,
                            "2021-10-01": -422.4,
                            "2021-09-25": -422.4,
                            "2021-09-28": -422.4,
                            "2021-09-29": -422.4,
                            "2021-09-26": -422.4,
                            "2021-09-27": -422.4
                        },
                        "before": 189322.23,
                        "after": 147671.34,
                        "source": {
                            "endDate": "2021-10-15",
                            "subtype": "",
                            "scope": "ALL_PRODUCTS",
                            "typeString": "PERCENTAGE",
                            "discount": {
                                "applyToNewCustomersOnly": false,
                                "discountedProducts": {},
                                "type": "PERCENTAGE",
                                "packageDiscount": 22.0,
                                "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                "subtype": "",
                                "discountedCategories": {},
                                "scope": "ALL_PRODUCTS",
                                "name": {
                                    "en": "discount",
                                    "fr": "escompte"
                                },
                                "id": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                "credit": false,
                                "startDate": "2021-05-08T00:00:00Z"
                            },
                            "discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                            "type": "PERCENTAGE",
                            "startDate": "2021-09-15",
                            "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
                        },
                        "type": "PERCENTAGE"
                    },
                    {
                        "amount": 0.0,
                        "dailyDeltas": {
                            "2021-09-25": 0.0
                        },
                        "before": 147671.34,
                        "after": 147671.34,
                        "source": {
                            "endDate": "2021-10-15",
                            "subtype": "",
                            "scope": "ALL_PRODUCTS",
                            "typeString": "CREDIT",
                            "discount": {
                                "applyToNewCustomersOnly": false,
                                "discountedProducts": {},
                                "type": "CREDIT",
                                "packageDiscount": 250000.0,
                                "cutoffDate": "2021-09-27T00:00:00Z",
                                "referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c",
                                "durationDays": 90,
                                "subtype": "",
                                "discountedCategories": {},
                                "scope": "ALL_PRODUCTS",
                                "name": {
                                    "en": "bbbb",
                                    "fr": "bb"
                                },
                                "id": "532067ee-c194-4463-b5a1-a161e5c9388c",
                                "credit": true,
                                "startDate": "2021-05-08T00:00:00Z"
                            },
                            "used": {
                                "packageDiscount": 0.0
                            },
                            "discountId": "532067ee-c194-4463-b5a1-a161e5c9388c",
                            "type": "CREDIT",
                            "startDate": "2021-09-15",
                            "remaining": {
                                "discountedProducts": {},
                                "discountedCategories": {},
                                "packageDiscount": 0.0
                            },
                            "referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c"
                        },
                        "type": "CREDIT"
                    }
                ],
                "adjustmentAggregations": [
                    {
                        "scopedBefore": 189322.23,
                        "scopedAmount": -41650.89,
                        "subtype": "",
                        "before": 251748.98,
                        "cumulativeAmount": -104077.64,
                        "after": 147671.34,
                        "type": "PERCENTAGE",
                        "scopedAfter": 147671.34
                    },
                    {
                        "scopedBefore": 147671.34,
                        "scopedAmount": 0.0,
                        "subtype": "",
                        "before": 147671.34,
                        "cumulativeAmount": 0.0,
                        "after": 147671.34,
                        "type": "CREDIT",
                        "scopedAfter": 147671.34
                    }
                ],
                "endDate": "2021-10-15T00:00:00Z",
                "inclusiveEndDate": "2021-10-14T00:00:00Z",
                "subTotal": 147671.34,
                "dateToSubTotalCost": {
                    "2021-10-06": 34144.890624,
                    "2021-10-07": 32116.48128,
                    "2021-10-08": 21359.336693999998,
                    "2021-10-02": 1497.6,
                    "2021-10-03": 1497.6,
                    "2021-10-04": 12766.995072,
                    "2021-10-05": 33805.234943999996,
                    "2021-09-30": 1497.6,
                    "2021-10-01": 1497.6,
                    "2021-09-25": 1497.6,
                    "2021-09-28": 1497.6,
                    "2021-09-29": 1497.6,
                    "2021-09-26": 1497.6,
                    "2021-09-27": 1497.6
                },
                "dateToTotalCost": {
                    "2021-10-06": 34144.890624,
                    "2021-10-07": 32116.48128,
                    "2021-10-08": 21359.336693999998,
                    "2021-10-02": 1497.6,
                    "2021-10-03": 1497.6,
                    "2021-10-04": 12766.995072,
                    "2021-10-05": 33805.234943999996,
                    "2021-09-30": 1497.6,
                    "2021-10-01": 1497.6,
                    "2021-09-25": 1497.6,
                    "2021-09-28": 1497.6,
                    "2021-09-29": 1497.6,
                    "2021-09-26": 1497.6,
                    "2021-09-27": 1497.6
                },
                "total": 147671.34,
                "currency": "CAD",
                "categories": [
                    {
                        "dateToTotalCost": {
                            "2021-10-06": 34144.890624,
                            "2021-10-07": 32116.48128,
                            "2021-10-08": 21359.336693999998,
                            "2021-10-02": 1497.6,
                            "2021-10-03": 1497.6,
                            "2021-10-04": 12766.995072,
                            "2021-10-05": 33805.234943999996,
                            "2021-09-30": 1497.6,
                            "2021-10-01": 1497.6,
                            "2021-09-25": 1497.6,
                            "2021-09-28": 1497.6,
                            "2021-09-29": 1497.6,
                            "2021-09-26": 1497.6,
                            "2021-09-27": 1497.6
                        },
                        "total": 147671.34,
                        "adjustments": [
                            {
                                "itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                                "amount": -47330.56,
                                "dailyDeltas": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": -1536.384,
                                    "2021-10-08": -1021.80096,
                                    "2021-10-02": -480.0,
                                    "2021-10-03": -480.0,
                                    "2021-10-04": -779.952,
                                    "2021-10-05": -2289.984,
                                    "2021-09-30": -480.0,
                                    "2021-10-01": -480.0,
                                    "2021-09-25": -480.0,
                                    "2021-09-28": -480.0,
                                    "2021-09-29": -480.0,
                                    "2021-09-26": -480.0,
                                    "2021-09-27": -480.0
                                },
                                "before": 236652.79,
                                "after": 189322.23,
                                "source": {
                                    "endDate": "2021-10-15",
                                    "subtype": "",
                                    "scope": "CATEGORIES",
                                    "typeString": "PERCENTAGE",
                                    "discount": {
                                        "applyToNewCustomersOnly": false,
                                        "discountedProducts": {},
                                        "type": "PERCENTAGE",
                                        "referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                        "subtype": "",
                                        "discountedCategories": {
                                            "950d5a79-f6df-4770-995a-5144e6feb6b0": 20
                                        },
                                        "scope": "CATEGORIES",
                                        "name": {
                                            "en": "compute-20-percent",
                                            "fr": "compute-20-percent"
                                        },
                                        "id": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                        "credit": false,
                                        "startDate": "2021-05-08T00:00:00Z"
                                    },
                                    "discountId": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                    "type": "PERCENTAGE",
                                    "startDate": "2021-09-15",
                                    "referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889"
                                },
                                "type": "PERCENTAGE"
                            },
                            {
                                "itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                                "amount": -41650.89,
                                "dailyDeltas": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": -1352.01792,
                                    "2021-10-08": -899.184845,
                                    "2021-10-02": -422.4,
                                    "2021-10-03": -422.4,
                                    "2021-10-04": -686.35776,
                                    "2021-10-05": -2015.18592,
                                    "2021-09-30": -422.4,
                                    "2021-10-01": -422.4,
                                    "2021-09-25": -422.4,
                                    "2021-09-28": -422.4,
                                    "2021-09-29": -422.4,
                                    "2021-09-26": -422.4,
                                    "2021-09-27": -422.4
                                },
                                "before": 189322.23,
                                "after": 147671.34,
                                "source": {
                                    "endDate": "2021-10-15",
                                    "subtype": "",
                                    "scope": "ALL_PRODUCTS",
                                    "typeString": "PERCENTAGE",
                                    "discount": {
                                        "applyToNewCustomersOnly": false,
                                        "discountedProducts": {},
                                        "type": "PERCENTAGE",
                                        "packageDiscount": 22.0,
                                        "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                        "subtype": "",
                                        "discountedCategories": {},
                                        "scope": "ALL_PRODUCTS",
                                        "name": {
                                            "en": "discount",
                                            "fr": "escompte"
                                        },
                                        "id": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                        "credit": false,
                                        "startDate": "2021-05-08T00:00:00Z"
                                    },
                                    "discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                    "type": "PERCENTAGE",
                                    "startDate": "2021-09-15",
                                    "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
                                },
                                "type": "PERCENTAGE"
                            }
                        ],
                        "adjustmentAggregations": [
                            {
                                "scopedBefore": 236652.79,
                                "scopedAmount": -88981.45,
                                "subtype": "",
                                "before": 251748.98,
                                "cumulativeAmount": -104077.64,
                                "after": 147671.34,
                                "type": "PERCENTAGE",
                                "scopedAfter": 147671.34
                            }
                        ],
                        "name": {
                            "en": "compute",
                            "fr": "dancer"
                        },
                        "subTotal": 147671.34,
                        "dateToSubTotalCost": {
                            "2021-10-06": 34144.890624,
                            "2021-10-07": 32116.48128,
                            "2021-10-08": 21359.336693999998,
                            "2021-10-02": 1497.6,
                            "2021-10-03": 1497.6,
                            "2021-10-04": 12766.995072,
                            "2021-10-05": 33805.234943999996,
                            "2021-09-30": 1497.6,
                            "2021-10-01": 1497.6,
                            "2021-09-25": 1497.6,
                            "2021-09-28": 1497.6,
                            "2021-09-29": 1497.6,
                            "2021-09-26": 1497.6,
                            "2021-09-27": 1497.6
                        },
                        "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                        "products": [
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 49740.6,
                                        "cumulativeAmount": -18702.47,
                                        "after": 31038.13,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "1f656184-df81-47c7-964f-eb9e27743d7b",
                                "usage": 497.406048,
                                "pricingTiers": [],
                                "subTotal": 31038.13,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": 4793.51808,
                                    "2021-10-08": 3188.018995,
                                    "2021-10-02": 1497.6,
                                    "2021-10-03": 1497.6,
                                    "2021-10-04": 2433.450239999999,
                                    "2021-10-05": 7144.75008,
                                    "2021-09-30": 1497.6,
                                    "2021-10-01": 1497.6,
                                    "2021-09-25": 1497.6,
                                    "2021-09-28": 1497.6,
                                    "2021-09-29": 1497.6,
                                    "2021-09-26": 1497.6,
                                    "2021-09-27": 1497.6
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": 4793.51808,
                                    "2021-10-08": 3188.018995,
                                    "2021-10-02": 1497.6,
                                    "2021-10-03": 1497.6,
                                    "2021-10-04": 2433.450239999999,
                                    "2021-10-05": 7144.75008,
                                    "2021-09-30": 1497.6,
                                    "2021-10-01": 1497.6,
                                    "2021-09-25": 1497.6,
                                    "2021-09-28": 1497.6,
                                    "2021-09-29": 1497.6,
                                    "2021-09-26": 1497.6,
                                    "2021-09-27": 1497.6
                                },
                                "total": 31038.13,
                                "unit": {
                                    "unit": "UNIT",
                                    "name": {}
                                },
                                "price": "100.000000",
                                "name": {
                                    "en": "specification",
                                    "fr": "specification"
                                },
                                "sku": "SPEC_PRODUCT",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 160493.81,
                                        "cumulativeAmount": -60345.67,
                                        "after": 100148.14,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "3c2bb895-4282-41a1-8db4-2269037dc561",
                                "usage": 8024.690304,
                                "pricingTiers": [],
                                "subTotal": 100148.14,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 29951.640576,
                                    "2021-10-07": 23967.500544,
                                    "2021-10-08": 15939.734353999998,
                                    "2021-10-04": 8630.129664,
                                    "2021-10-05": 21659.129856
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 29951.640576,
                                    "2021-10-07": 23967.500544,
                                    "2021-10-08": 15939.734353999998,
                                    "2021-10-04": 8630.129664,
                                    "2021-10-05": 21659.129856
                                },
                                "total": 100148.14,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "20.000000",
                                "name": {
                                    "en": "storage",
                                    "fr": "storage"
                                },
                                "sku": "STORAGE",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 11322.18,
                                        "cumulativeAmount": -4257.14,
                                        "after": 7065.04,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "6b94a874-9f85-4a14-9437-d5df30c8191d",
                                "usage": 377.406048,
                                "pricingTiers": [],
                                "subTotal": 7065.04,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 1797.12,
                                    "2021-10-07": 1438.055424,
                                    "2021-10-08": 956.405699,
                                    "2021-10-04": 730.0350719999999,
                                    "2021-10-05": 2143.4250239999997
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 1797.12,
                                    "2021-10-07": 1438.055424,
                                    "2021-10-08": 956.405699,
                                    "2021-10-04": 730.0350719999999,
                                    "2021-10-05": 2143.4250239999997
                                },
                                "total": 7065.04,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "30.000000",
                                "name": {
                                    "en": "vm cpu",
                                    "fr": "dancer"
                                },
                                "sku": "VM_CPU",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [
                                    {
                                        "itemId": "a36933e3-697a-4093-9057-18aed07479ea",
                                        "amount": -15096.19,
                                        "dailyDeltas": {
                                            "2021-10-06": -3839.952,
                                            "2021-10-07": -3072.768,
                                            "2021-10-08": -2043.55392,
                                            "2021-10-04": -1559.904,
                                            "2021-10-05": -4580.016
                                        },
                                        "before": 30192.39,
                                        "after": 15096.2,
                                        "source": {
                                            "endDate": "2021-10-15",
                                            "subtype": "",
                                            "scope": "PRODUCTS",
                                            "typeString": "PERCENTAGE",
                                            "discount": {
                                                "applyToNewCustomersOnly": false,
                                                "discountedProducts": {
                                                    "a36933e3-697a-4093-9057-18aed07479ea": 50
                                                },
                                                "type": "PERCENTAGE",
                                                "referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                                "subtype": "",
                                                "discountedCategories": {},
                                                "scope": "PRODUCTS",
                                                "name": {
                                                    "en": "vm-ram-50-percent",
                                                    "fr": "vm-ram-50-percent"
                                                },
                                                "id": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                                "credit": false,
                                                "startDate": "2021-05-08T00:00:00Z"
                                            },
                                            "discountId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                            "type": "PERCENTAGE",
                                            "startDate": "2021-09-15",
                                            "referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99"
                                        },
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "adjustmentAggregations": [
                                    {
                                        "scopedBefore": 30192.39,
                                        "scopedAmount": -15096.19,
                                        "subtype": "",
                                        "before": 30192.39,
                                        "cumulativeAmount": -20772.36,
                                        "after": 9420.03,
                                        "type": "PERCENTAGE",
                                        "scopedAfter": 15096.2
                                    }
                                ],
                                "productId": "a36933e3-697a-4093-9057-18aed07479ea",
                                "usage": 754.809696,
                                "pricingTiers": [],
                                "subTotal": 9420.03,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 2396.1300479999995,
                                    "2021-10-07": 1917.407231999999,
                                    "2021-10-08": 1275.1776459999996,
                                    "2021-10-04": 973.380096,
                                    "2021-10-05": 2857.929984
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 2396.1300479999995,
                                    "2021-10-07": 1917.407231999999,
                                    "2021-10-08": 1275.1776459999996,
                                    "2021-10-04": 973.380096,
                                    "2021-10-05": 2857.929984
                                },
                                "total": 9420.03,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "40.000000",
                                "name": {
                                    "en": "ram",
                                    "fr": "ram"
                                },
                                "sku": "VM_RAM",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            }
                        ]
                    }
                ],
                "startDate": "2021-09-15T00:00:00Z"
            },
            "status": "USAGE_PENDING"
        }
    ]
}

Optional Query Parameters
includeAllSubOrgs boolean	Whether or not to include sub-organizations of sub-organizations or just direct sub-organizations of the reseller.
billingCycle String	The cycle which the invoice belongs to. Format is MM-YYYY

Attributes
id UUID	The UUID of the invoice.
invoiceId string	The human readable id.
status enum	The status of the invoice. Possible values are: USAGE_PENDING, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID.
createdDate date	The created date of the invoice.
draftedDate date	The date the invoice was drafted. Is null if status is still USAGE_PENDING.
issuedDate date	The date the invoice was issued.
dueDate date	The date the invoice is due.
organization.id UUID	The UUID of the organization the invoice belongs to.
organization.name string	The name of the organization the invoice belongs to.
balance BigDecimal	The invoice's remaining balance.
detail Object	The invoice detail contains a currency and a list of categories. Each category has a list of products.
detail.currency string	The short-name of the currency.
detail.subTotal string	A string containing the total before taxes and credits.
detail.total string	The invoice total after discounts, taxes, and credits.
detail.startDate string	An ISO-8601 instant format string representing the start of the invoice detail report.
detail.endDate string	An ISO-8601 instant format string representing the end of the invoice detail report.
detail.adjustments Array[Object]	The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax.
detail.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.adjustments.amount string	The adjustment amount applied to the invoice total.
detail.adjustments.before string	The invoice total before the adjustment was applied.
detail.adjustments.after string	The invoice total after the adjustment was applied.
detail.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.adjustmentAggregations.before string	The invoice total before the adjustments were applied.
detail.adjustmentAggregations.after string	The invoice total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.adjustmentAggregations.cumulativeAmount string	The cumulative adjustment amount applied to the invoice, its categories and their products.
detail.categories Array[Object]	An array of category objects. Contains all categories that had usage for the period.
detail.categories.name Object	A map of short language codes to their translated category names.
detail.categories.subTotal string	A string with the category subtotal, before taxes and credits.
detail.categories.total string	A string with the category subtotal, after taxes and credits.
detail.adjustments Array[Object]	The adjustments applied to the category. An adjustment tracks the application of a discount, a credit or a tax.
detail.categories.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.adjustments.itemId UUID	The category id.
detail.categories.adjustments.amount string	The adjustment amount applied to the category total.
detail.categories.adjustments.before string	The category total before the adjustment was applied.
detail.categories.adjustments.after string	The category total after the adjustment was applied.
detail.categories.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.categories.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.categories.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.categories.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.adjustmentAggregations.before string	The category total before the adjustments were applied.
detail.categories.adjustmentAggregations.after string	The category total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.adjustmentAggregations.cumulativeAmount string	The cumulative adjustment amount applied to the category and its products.
detail.categories.products Object	A map of short language codes to their translated category names.
detail.categories.products.sku string	A unique string representing the sku for a product.
detail.categories.products.name Object	The name object in each language for the product name.
detail.categories.products.cost string	A string of the summed up total cost for the product.
detail.categories.products.usage Object	A string of the summed up total usage for the product.
detail.categories.products.price Object	A string representing the average unit price over the period.
detail.categories.products.subTotal string	A string with the product subtotal, before taxes and credits.
detail.categories.products.total string	A string with the product total, after taxes and credits.
detail.categories.products.period string	The period for the product capture. Possible values: HOURS, MONTH.
detail.categories.products.unit Object	The unit object of the product.
detail.categories.products.unit.unit Object	The unit value of the product.
detail.categories.products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
detail.categories.products.adjustments Array[Object]	The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax.
detail.categories.products.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.products.adjustments.itemId UUID	The product id.
detail.categories.products.adjustments.amount string	The adjustment amount applied to the product total.
detail.categories.products.adjustments.before string	The product total before the adjustment was applied.
detail.categories.products.adjustments.after string	The product total after the adjustment was applied.
detail.categories.products.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.categories.products.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.categories.products.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.categories.products.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.products.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.before string	The product total before the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.after string	The product total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.cumulativeAmount string	The adjustment amount applied to the product total.

List invoices of organization

GET /invoices?organization_id=:organization_id&billingCycle=MM-YYYY

Retrieve the list of invoices associated with an organization.

# Retrieve list of invoices of an organization
curl "https://cloudmc_endpoint/rest/invoices?organization_id=289ec5fb-0970-44e3-bca8-777a691e23c7&billingCycle=07-2021" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "createdDate": "2021-11-22T17:22:49Z",
            "billingCycle": {
                "id": "7c10604c-3045-40ef-9890-1bd5a23d5a7b"
            },
            "organization": {
                "name": "System",
                "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
            },
            "invoiceId": "X5GDVRKGCY",
            "id": "504735ce-cdc1-4adf-b59c-b4e43d1eefa4",
            "detail": {
                "adjustments": [
                    {
                        "amount": -41650.89,
                        "dailyDeltas": {
                            "2021-10-06": 0.0,
                            "2021-10-07": -1352.01792,
                            "2021-10-08": -899.184845,
                            "2021-10-02": -422.4,
                            "2021-10-03": -422.4,
                            "2021-10-04": -686.35776,
                            "2021-10-05": -2015.18592,
                            "2021-09-30": -422.4,
                            "2021-10-01": -422.4,
                            "2021-09-25": -422.4,
                            "2021-09-28": -422.4,
                            "2021-09-29": -422.4,
                            "2021-09-26": -422.4,
                            "2021-09-27": -422.4
                        },
                        "before": 189322.23,
                        "after": 147671.34,
                        "source": {
                            "endDate": "2021-10-15",
                            "subtype": "",
                            "scope": "ALL_PRODUCTS",
                            "typeString": "PERCENTAGE",
                            "discount": {
                                "applyToNewCustomersOnly": false,
                                "discountedProducts": {},
                                "type": "PERCENTAGE",
                                "packageDiscount": 22.0,
                                "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                "subtype": "",
                                "discountedCategories": {},
                                "scope": "ALL_PRODUCTS",
                                "name": {
                                    "en": "discount",
                                    "fr": "escompte"
                                },
                                "id": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                "credit": false,
                                "startDate": "2021-05-08T00:00:00Z"
                            },
                            "discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                            "type": "PERCENTAGE",
                            "startDate": "2021-09-15",
                            "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
                        },
                        "type": "PERCENTAGE"
                    },
                    {
                        "amount": 0.0,
                        "dailyDeltas": {
                            "2021-09-25": 0.0
                        },
                        "before": 147671.34,
                        "after": 147671.34,
                        "source": {
                            "endDate": "2021-10-15",
                            "subtype": "",
                            "scope": "ALL_PRODUCTS",
                            "typeString": "CREDIT",
                            "discount": {
                                "applyToNewCustomersOnly": false,
                                "discountedProducts": {},
                                "type": "CREDIT",
                                "packageDiscount": 250000.0,
                                "cutoffDate": "2021-09-27T00:00:00Z",
                                "referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c",
                                "durationDays": 90,
                                "subtype": "",
                                "discountedCategories": {},
                                "scope": "ALL_PRODUCTS",
                                "name": {
                                    "en": "bbbb",
                                    "fr": "bb"
                                },
                                "id": "532067ee-c194-4463-b5a1-a161e5c9388c",
                                "credit": true,
                                "startDate": "2021-05-08T00:00:00Z"
                            },
                            "used": {
                                "packageDiscount": 0.0
                            },
                            "discountId": "532067ee-c194-4463-b5a1-a161e5c9388c",
                            "type": "CREDIT",
                            "startDate": "2021-09-15",
                            "remaining": {
                                "discountedProducts": {},
                                "discountedCategories": {},
                                "packageDiscount": 0.0
                            },
                            "referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c"
                        },
                        "type": "CREDIT"
                    }
                ],
                "adjustmentAggregations": [
                    {
                        "scopedBefore": 189322.23,
                        "scopedAmount": -41650.89,
                        "subtype": "",
                        "before": 251748.98,
                        "cumulativeAmount": -104077.64,
                        "after": 147671.34,
                        "type": "PERCENTAGE",
                        "scopedAfter": 147671.34
                    },
                    {
                        "scopedBefore": 147671.34,
                        "scopedAmount": 0.0,
                        "subtype": "",
                        "before": 147671.34,
                        "cumulativeAmount": 0.0,
                        "after": 147671.34,
                        "type": "CREDIT",
                        "scopedAfter": 147671.34
                    }
                ],
                "endDate": "2021-10-15T00:00:00Z",
                "inclusiveEndDate": "2021-10-14T00:00:00Z",
                "subTotal": 147671.34,
                "dateToSubTotalCost": {
                    "2021-10-06": 34144.890624,
                    "2021-10-07": 32116.48128,
                    "2021-10-08": 21359.336693999998,
                    "2021-10-02": 1497.6,
                    "2021-10-03": 1497.6,
                    "2021-10-04": 12766.995072,
                    "2021-10-05": 33805.234943999996,
                    "2021-09-30": 1497.6,
                    "2021-10-01": 1497.6,
                    "2021-09-25": 1497.6,
                    "2021-09-28": 1497.6,
                    "2021-09-29": 1497.6,
                    "2021-09-26": 1497.6,
                    "2021-09-27": 1497.6
                },
                "dateToTotalCost": {
                    "2021-10-06": 34144.890624,
                    "2021-10-07": 32116.48128,
                    "2021-10-08": 21359.336693999998,
                    "2021-10-02": 1497.6,
                    "2021-10-03": 1497.6,
                    "2021-10-04": 12766.995072,
                    "2021-10-05": 33805.234943999996,
                    "2021-09-30": 1497.6,
                    "2021-10-01": 1497.6,
                    "2021-09-25": 1497.6,
                    "2021-09-28": 1497.6,
                    "2021-09-29": 1497.6,
                    "2021-09-26": 1497.6,
                    "2021-09-27": 1497.6
                },
                "total": 147671.34,
                "currency": "CAD",
                "categories": [
                    {
                        "dateToTotalCost": {
                            "2021-10-06": 34144.890624,
                            "2021-10-07": 32116.48128,
                            "2021-10-08": 21359.336693999998,
                            "2021-10-02": 1497.6,
                            "2021-10-03": 1497.6,
                            "2021-10-04": 12766.995072,
                            "2021-10-05": 33805.234943999996,
                            "2021-09-30": 1497.6,
                            "2021-10-01": 1497.6,
                            "2021-09-25": 1497.6,
                            "2021-09-28": 1497.6,
                            "2021-09-29": 1497.6,
                            "2021-09-26": 1497.6,
                            "2021-09-27": 1497.6
                        },
                        "total": 147671.34,
                        "adjustments": [
                            {
                                "itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                                "amount": -47330.56,
                                "dailyDeltas": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": -1536.384,
                                    "2021-10-08": -1021.80096,
                                    "2021-10-02": -480.0,
                                    "2021-10-03": -480.0,
                                    "2021-10-04": -779.952,
                                    "2021-10-05": -2289.984,
                                    "2021-09-30": -480.0,
                                    "2021-10-01": -480.0,
                                    "2021-09-25": -480.0,
                                    "2021-09-28": -480.0,
                                    "2021-09-29": -480.0,
                                    "2021-09-26": -480.0,
                                    "2021-09-27": -480.0
                                },
                                "before": 236652.79,
                                "after": 189322.23,
                                "source": {
                                    "endDate": "2021-10-15",
                                    "subtype": "",
                                    "scope": "CATEGORIES",
                                    "typeString": "PERCENTAGE",
                                    "discount": {
                                        "applyToNewCustomersOnly": false,
                                        "discountedProducts": {},
                                        "type": "PERCENTAGE",
                                        "referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                        "subtype": "",
                                        "discountedCategories": {
                                            "950d5a79-f6df-4770-995a-5144e6feb6b0": 20
                                        },
                                        "scope": "CATEGORIES",
                                        "name": {
                                            "en": "compute-20-percent",
                                            "fr": "compute-20-percent"
                                        },
                                        "id": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                        "credit": false,
                                        "startDate": "2021-05-08T00:00:00Z"
                                    },
                                    "discountId": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                    "type": "PERCENTAGE",
                                    "startDate": "2021-09-15",
                                    "referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889"
                                },
                                "type": "PERCENTAGE"
                            },
                            {
                                "itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                                "amount": -41650.89,
                                "dailyDeltas": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": -1352.01792,
                                    "2021-10-08": -899.184845,
                                    "2021-10-02": -422.4,
                                    "2021-10-03": -422.4,
                                    "2021-10-04": -686.35776,
                                    "2021-10-05": -2015.18592,
                                    "2021-09-30": -422.4,
                                    "2021-10-01": -422.4,
                                    "2021-09-25": -422.4,
                                    "2021-09-28": -422.4,
                                    "2021-09-29": -422.4,
                                    "2021-09-26": -422.4,
                                    "2021-09-27": -422.4
                                },
                                "before": 189322.23,
                                "after": 147671.34,
                                "source": {
                                    "endDate": "2021-10-15",
                                    "subtype": "",
                                    "scope": "ALL_PRODUCTS",
                                    "typeString": "PERCENTAGE",
                                    "discount": {
                                        "applyToNewCustomersOnly": false,
                                        "discountedProducts": {},
                                        "type": "PERCENTAGE",
                                        "packageDiscount": 22.0,
                                        "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                        "subtype": "",
                                        "discountedCategories": {},
                                        "scope": "ALL_PRODUCTS",
                                        "name": {
                                            "en": "discount",
                                            "fr": "escompte"
                                        },
                                        "id": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                        "credit": false,
                                        "startDate": "2021-05-08T00:00:00Z"
                                    },
                                    "discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                    "type": "PERCENTAGE",
                                    "startDate": "2021-09-15",
                                    "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
                                },
                                "type": "PERCENTAGE"
                            }
                        ],
                        "adjustmentAggregations": [
                            {
                                "scopedBefore": 236652.79,
                                "scopedAmount": -88981.45,
                                "subtype": "",
                                "before": 251748.98,
                                "cumulativeAmount": -104077.64,
                                "after": 147671.34,
                                "type": "PERCENTAGE",
                                "scopedAfter": 147671.34
                            }
                        ],
                        "name": {
                            "en": "compute",
                            "fr": "dancer"
                        },
                        "subTotal": 147671.34,
                        "dateToSubTotalCost": {
                            "2021-10-06": 34144.890624,
                            "2021-10-07": 32116.48128,
                            "2021-10-08": 21359.336693999998,
                            "2021-10-02": 1497.6,
                            "2021-10-03": 1497.6,
                            "2021-10-04": 12766.995072,
                            "2021-10-05": 33805.234943999996,
                            "2021-09-30": 1497.6,
                            "2021-10-01": 1497.6,
                            "2021-09-25": 1497.6,
                            "2021-09-28": 1497.6,
                            "2021-09-29": 1497.6,
                            "2021-09-26": 1497.6,
                            "2021-09-27": 1497.6
                        },
                        "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                        "products": [
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 49740.6,
                                        "cumulativeAmount": -18702.47,
                                        "after": 31038.13,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "1f656184-df81-47c7-964f-eb9e27743d7b",
                                "usage": 497.406048,
                                "pricingTiers": [],
                                "subTotal": 31038.13,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": 4793.51808,
                                    "2021-10-08": 3188.018995,
                                    "2021-10-02": 1497.6,
                                    "2021-10-03": 1497.6,
                                    "2021-10-04": 2433.450239999999,
                                    "2021-10-05": 7144.75008,
                                    "2021-09-30": 1497.6,
                                    "2021-10-01": 1497.6,
                                    "2021-09-25": 1497.6,
                                    "2021-09-28": 1497.6,
                                    "2021-09-29": 1497.6,
                                    "2021-09-26": 1497.6,
                                    "2021-09-27": 1497.6
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 0.0,
                                    "2021-10-07": 4793.51808,
                                    "2021-10-08": 3188.018995,
                                    "2021-10-02": 1497.6,
                                    "2021-10-03": 1497.6,
                                    "2021-10-04": 2433.450239999999,
                                    "2021-10-05": 7144.75008,
                                    "2021-09-30": 1497.6,
                                    "2021-10-01": 1497.6,
                                    "2021-09-25": 1497.6,
                                    "2021-09-28": 1497.6,
                                    "2021-09-29": 1497.6,
                                    "2021-09-26": 1497.6,
                                    "2021-09-27": 1497.6
                                },
                                "total": 31038.13,
                                "unit": {
                                    "unit": "UNIT",
                                    "name": {}
                                },
                                "price": "100.000000",
                                "name": {
                                    "en": "specification",
                                    "fr": "specification"
                                },
                                "sku": "SPEC_PRODUCT",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 160493.81,
                                        "cumulativeAmount": -60345.67,
                                        "after": 100148.14,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "3c2bb895-4282-41a1-8db4-2269037dc561",
                                "usage": 8024.690304,
                                "pricingTiers": [],
                                "subTotal": 100148.14,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 29951.640576,
                                    "2021-10-07": 23967.500544,
                                    "2021-10-08": 15939.734353999998,
                                    "2021-10-04": 8630.129664,
                                    "2021-10-05": 21659.129856
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 29951.640576,
                                    "2021-10-07": 23967.500544,
                                    "2021-10-08": 15939.734353999998,
                                    "2021-10-04": 8630.129664,
                                    "2021-10-05": 21659.129856
                                },
                                "total": 100148.14,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "20.000000",
                                "name": {
                                    "en": "storage",
                                    "fr": "storage"
                                },
                                "sku": "STORAGE",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 11322.18,
                                        "cumulativeAmount": -4257.14,
                                        "after": 7065.04,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "6b94a874-9f85-4a14-9437-d5df30c8191d",
                                "usage": 377.406048,
                                "pricingTiers": [],
                                "subTotal": 7065.04,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 1797.12,
                                    "2021-10-07": 1438.055424,
                                    "2021-10-08": 956.405699,
                                    "2021-10-04": 730.0350719999999,
                                    "2021-10-05": 2143.4250239999997
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 1797.12,
                                    "2021-10-07": 1438.055424,
                                    "2021-10-08": 956.405699,
                                    "2021-10-04": 730.0350719999999,
                                    "2021-10-05": 2143.4250239999997
                                },
                                "total": 7065.04,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "30.000000",
                                "name": {
                                    "en": "vm cpu",
                                    "fr": "dancer"
                                },
                                "sku": "VM_CPU",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [
                                    {
                                        "itemId": "a36933e3-697a-4093-9057-18aed07479ea",
                                        "amount": -15096.19,
                                        "dailyDeltas": {
                                            "2021-10-06": -3839.952,
                                            "2021-10-07": -3072.768,
                                            "2021-10-08": -2043.55392,
                                            "2021-10-04": -1559.904,
                                            "2021-10-05": -4580.016
                                        },
                                        "before": 30192.39,
                                        "after": 15096.2,
                                        "source": {
                                            "endDate": "2021-10-15",
                                            "subtype": "",
                                            "scope": "PRODUCTS",
                                            "typeString": "PERCENTAGE",
                                            "discount": {
                                                "applyToNewCustomersOnly": false,
                                                "discountedProducts": {
                                                    "a36933e3-697a-4093-9057-18aed07479ea": 50
                                                },
                                                "type": "PERCENTAGE",
                                                "referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                                "subtype": "",
                                                "discountedCategories": {},
                                                "scope": "PRODUCTS",
                                                "name": {
                                                    "en": "vm-ram-50-percent",
                                                    "fr": "vm-ram-50-percent"
                                                },
                                                "id": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                                "credit": false,
                                                "startDate": "2021-05-08T00:00:00Z"
                                            },
                                            "discountId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                            "type": "PERCENTAGE",
                                            "startDate": "2021-09-15",
                                            "referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99"
                                        },
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "adjustmentAggregations": [
                                    {
                                        "scopedBefore": 30192.39,
                                        "scopedAmount": -15096.19,
                                        "subtype": "",
                                        "before": 30192.39,
                                        "cumulativeAmount": -20772.36,
                                        "after": 9420.03,
                                        "type": "PERCENTAGE",
                                        "scopedAfter": 15096.2
                                    }
                                ],
                                "productId": "a36933e3-697a-4093-9057-18aed07479ea",
                                "usage": 754.809696,
                                "pricingTiers": [],
                                "subTotal": 9420.03,
                                "dateToSubTotalCost": {
                                    "2021-10-06": 2396.1300479999995,
                                    "2021-10-07": 1917.407231999999,
                                    "2021-10-08": 1275.1776459999996,
                                    "2021-10-04": 973.380096,
                                    "2021-10-05": 2857.929984
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-10-06": 2396.1300479999995,
                                    "2021-10-07": 1917.407231999999,
                                    "2021-10-08": 1275.1776459999996,
                                    "2021-10-04": 973.380096,
                                    "2021-10-05": 2857.929984
                                },
                                "total": 9420.03,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "40.000000",
                                "name": {
                                    "en": "ram",
                                    "fr": "ram"
                                },
                                "sku": "VM_RAM",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            }
                        ]
                    }
                ],
                "startDate": "2021-09-15T00:00:00Z"
            },
            "status": "USAGE_PENDING"
        }
    ]
}

Optional Query Parameters
organization_id UUID	The UUID of the organization the invoice belongs to.
billingCycle String	The cycle which the invoice belongs to. Format is MM-YYYY

Attributes
id UUID	The UUID of the invoice.
invoiceId string	The human readable id.
status enum	The status of the invoice. Possible values are: USAGE_PENDING, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID.
createdDate date	The created date of the invoice.
draftedDate date	The date the invoice was drafted. Is null if status is still USAGE_PENDING.
issuedDate date	The date the invoice was issued.
dueDate date	The date the invoice is due.
organization.id UUID	The UUID of the organization the invoice belongs to.
organization.name string	The name of the organization the invoice belongs to.
balance BigDecimal	The invoice's remaining balance.
detail Object	The invoice detail contains a currency and a list of categories. Each category has a list of products.
detail.currency string	The short-name of the currency.
detail.subTotal string	A string containing the total before taxes and credits.
detail.total string	The invoice total after discounts, taxes, and credits.
detail.startDate string	An ISO-8601 instant format string representing the start of the invoice detail report.
detail.endDate string	An ISO-8601 instant format string representing the end of the invoice detail report.
detail.adjustments Array[Object]	The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax.
detail.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.adjustments.amount string	The adjustment amount applied to the invoice total.
detail.adjustments.before string	The invoice total before the adjustment was applied.
detail.adjustments.after string	The invoice total after the adjustment was applied.
detail.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.adjustmentAggregations.before string	The invoice total before the adjustments were applied.
detail.adjustmentAggregations.after string	The invoice total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.adjustmentAggregations.cumulativeAmount string	The cumulative adjustment amount applied to the invoice, its categories and their products.
detail.categories Array[Object]	An array of category objects. Contains all categories that had usage for the period.
detail.categories.name Object	A map of short language codes to their translated category names.
detail.categories.subTotal string	A string with the category subtotal, before taxes and credits.
detail.categories.total string	A string with the category subtotal, after taxes and credits.
detail.adjustments Array[Object]	The adjustments applied to the category. An adjustment tracks the application of a discount, a credit or a tax.
detail.categories.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.adjustments.itemId UUID	The category id.
detail.categories.adjustments.amount string	The adjustment amount applied to the category total.
detail.categories.adjustments.before string	The category total before the adjustment was applied.
detail.categories.adjustments.after string	The category total after the adjustment was applied.
detail.categories.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.categories.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.categories.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.categories.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.adjustmentAggregations.before string	The category total before the adjustments were applied.
detail.categories.adjustmentAggregations.after string	The category total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.adjustmentAggregations.cumulativeAmount string	The cumulative adjustment amount applied to the category and its products.
detail.categories.products Object	A map of short language codes to their translated category names.
detail.categories.products.sku string	A unique string representing the sku for a product.
detail.categories.products.name Object	The name object in each language for the product name.
detail.categories.products.cost string	A string of the summed up total cost for the product.
detail.categories.products.usage Object	A string of the summed up total usage for the product.
detail.categories.products.price Object	A string representing the average unit price over the period.
detail.categories.products.subTotal string	A string with the product subtotal, before taxes and credits.
detail.categories.products.total string	A string with the product total, after taxes and credits.
detail.categories.products.period string	The period for the product capture. Possible values: HOURS, MONTH.
detail.categories.products.unit Object	The unit object of the product.
detail.categories.products.unit.unit Object	The unit value of the product.
detail.categories.products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
detail.categories.products.adjustments Array[Object]	The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax.
detail.categories.products.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.products.adjustments.itemId UUID	The product id.
detail.categories.products.adjustments.amount string	The adjustment amount applied to the product total.
detail.categories.products.adjustments.before string	The product total before the adjustment was applied.
detail.categories.products.adjustments.after string	The product total after the adjustment was applied.
detail.categories.products.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.categories.products.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.categories.products.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.categories.products.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.products.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.before string	The product total before the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.after string	The product total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.cumulativeAmount string	The adjustment amount applied to the product total.

List invoices of organization as a csv

GET /invoices?organization_id=:organization_id&billingCycle=MM-YYYY

Retrieve the list of invoices associated with an organization as a csv report

# Retrieve list of invoices of an organization
curl "https://cloudmc_endpoint/rest/invoices?organization_id=289ec5fb-0970-44e3-bca8-777a691e23c7&billingCycle=07-2021" \
   -H "MC-Api-Key: your_api_key"
   -H "Accept: text/csv"

The response is a list of priced products, with the first line as a header, for the given organization and billing cycle.

The format of the response is a CSV with , used as the delimiter.

organization,custom_field_1,custom_field_2,category,sku,usage,unit,currency,total_before_tax,tax_code,total_tax,tax_name1,tax_amount1,tax_name2,tax_amount2,invoice_number,status,due_date,credit_card_transaction_id,billing_start_date,billing_end_date,
AcmeCorp,null,null,Networking,BANDWIDTH,0.0043,GIGABYTE,USD,$0.00,SW056003,$0.00,QUEBEC QST/TVQ,$0.00,CANADA GST/TPS,$0.00,NFROFNGWHU,IN_REVIEW,null,null,9/20/21,10/20/21,
AcmeCorp,null,null,Compute,CCM-1M02,295.935,GIGABYTE,USD,$21.90,SW056003,$3.28,QUEBEC QST/TVQ,$2.18,CANADA GST/TPS,$1.10,NFROFNGWHU,IN_REVIEW,null,null,9/20/21,10/20/21,%         

Query Parameters

Optional
billingCycle String	The cycle which the invoice belongs to. Format is MM-YYYY. Defaults to the latest billing cycle.
organization_id UUID	The reseller for which you're building the report. If not passed will default to the calling user's organization.
language UUID	Language to use for the report fields (but not the headers). Expected values are "en" (English), "fr" (French) or "es" (Spanish). Defaults to "en".

Report Attributes
organization String	The organization name.
custom_field_1 String	The organization custom field (ex: account ID). Configured in the reseller billing settings. There can be more than one custom field.
category String	The product category.
sku String	The SKU of the product.
usage String	The total usage of the product.
unit String	The name of the unit of the product.
currency String	The short-name of the currency.
total_before_tax String	The total cost before taxes are applied.
tax_code String	The code of the tax.
total_tax String	The total tax.
tax_name1 String	The name of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax name.
tax_amount1 String	The amount of the tax. Depends on the tax_code, reseller billing address and customer billing address. There can be more than one tax amount.
invoice_number String	The human-readable number of the invoice.
status String	The status of the invoice. Possible values are: USAGE_PENDING, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID.
due_date String	The date the invoice is due.
credit_card_transaction_id String	The confirmation number returned from the payment provider for the invoice.
billing_start_date String	The billing start date of the invoice.
billing_end_date String	The billing end date of the invoice.

Approve invoice

PUT /invoices/:invoice_id/approve

Manually approve an invoice in the 'IN_REVIEW' state and issue the invoice to the customer by email. If the invoice is already in the 'ISSUED' state, an empty response will be returned and an email will not be sent. If the invoice is in any other state, an error will be thrown.

# Approve a draft invoice
curl -X PUT "https://cloudmc_endpoint/rest/invoices/20e9b8d8-b1cb-4462-b6e8-fbb8416b2cbb/approve" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "draftedDate": "2021-11-19T17:14:44Z",
            "createdDate": "2021-11-19T17:14:44Z",
            "billingCycle": {
                "id": "bf5d38ba-74f4-459a-be5f-2fd771cf0a68"
            },
            "organization": {
                "customFields": {},
                "name": "System",
                "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
            },
            "invoiceId": "ZASBNWS5IH",
            "id": "150006dd-697c-4021-82ab-483f5a132c2c",
            "detail": {
                "adjustments": [
                    {
                        "amount": -28891.86,
                        "dailyDeltas": {
                            "2021-08-11": 2111.974656,
                            "2021-08-10": 2111.974656,
                            "2021-08-13": 2111.974656,
                            "2021-08-12": 4223.949312,
                            "2021-08-04": 4223.949312,
                            "2021-08-14": 2111.974656,
                            "2021-08-06": 2111.974656,
                            "2021-08-05": 0.0,
                            "2021-08-08": 2111.974656,
                            "2021-08-07": 2111.974656,
                            "2021-08-09": 2111.974656
                        },
                        "before": 131326.62,
                        "after": 102434.76,
                        "source": {
                            "endDate": "2021-08-15",
                            "subtype": "",
                            "scope": "ALL_PRODUCTS",
                            "typeString": "PERCENTAGE",
                            "discount": {
                                "applyToNewCustomersOnly": false,
                                "discountedProducts": {},
                                "type": "PERCENTAGE",
                                "packageDiscount": 22.0,
                                "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                "subtype": "",
                                "discountedCategories": {},
                                "scope": "ALL_PRODUCTS",
                                "name": {
                                    "en": "discount",
                                    "fr": "escompte"
                                },
                                "id": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                "credit": false,
                                "startDate": "2021-05-08T00:00:00Z"
                            },
                            "discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                            "type": "PERCENTAGE",
                            "startDate": "2021-08-04",
                            "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
                        },
                        "type": "PERCENTAGE"
                    },
                    {
                        "amount": -101934.76,
                        "dailyDeltas": {
                            "2021-08-11": 8536.230144,
                            "2021-08-10": 8536.230144,
                            "2021-08-13": 8536.230144,
                            "2021-08-12": 17072.460288,
                            "2021-08-04": 16572.460288,
                            "2021-08-14": 8536.230144,
                            "2021-08-06": 8536.230144,
                            "2021-08-05": 0.0,
                            "2021-08-08": 8536.230144,
                            "2021-08-07": 8536.230144,
                            "2021-08-09": 8536.230144
                        },
                        "before": 101934.76,
                        "after": 0.0,
                        "source": {
                            "endDate": "2021-08-15",
                            "subtype": "",
                            "scope": "ALL_PRODUCTS",
                            "typeString": "CREDIT",
                            "discount": {
                                "applyToNewCustomersOnly": false,
                                "discountedProducts": {},
                                "type": "CREDIT",
                                "packageDiscount": 250000.0,
                                "cutoffDate": "2021-09-27T00:00:00Z",
                                "referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c",
                                "durationDays": 90,
                                "subtype": "",
                                "discountedCategories": {},
                                "scope": "ALL_PRODUCTS",
                                "name": {
                                    "en": "3 month credit",
                                    "fr": "3 month credit fr"
                                },
                                "id": "532067ee-c194-4463-b5a1-a161e5c9388c",
                                "credit": true,
                                "startDate": "2021-05-08T00:00:00Z"
                            },
                            "used": {
                                "packageDiscount": -101934.76
                            },
                            "discountId": "532067ee-c194-4463-b5a1-a161e5c9388c",
                            "type": "CREDIT",
                            "startDate": "2021-08-04",
                            "remaining": {
                                "discountedProducts": {},
                                "discountedCategories": {},
                                "packageDiscount": 250000.0
                            },
                            "referenceId": "532067ee-c194-4463-b5a1-a161e5c9388c"
                        },
                        "type": "CREDIT"
                    }
                ],
                "adjustmentAggregations": [
                    {
                        "scopedBefore": 131326.62,
                        "scopedAmount": -28891.86,
                        "subtype": "",
                        "before": 175678.27,
                        "cumulativeAmount": -73243.51,
                        "after": 102434.76,
                        "type": "PERCENTAGE",
                        "scopedAfter": 102434.76
                    },
                    {
                        "scopedBefore": 101934.76,
                        "scopedAmount": -101934.76,
                        "subtype": "",
                        "before": 102434.76,
                        "cumulativeAmount": -102434.76,
                        "after": 0.0,
                        "type": "CREDIT",
                        "scopedAfter": 0.0
                    }
                ],
                "endDate": "2021-08-15T00:00:00Z",
                "inclusiveEndDate": "2021-08-14T00:00:00Z",
                "subTotal": 102434.76,
                "dateToSubTotalCost": {
                    "2021-08-11": 8536.230144,
                    "2021-08-10": 8536.230144,
                    "2021-08-13": 8536.230144,
                    "2021-08-12": 17072.460288,
                    "2021-08-04": 17072.460288,
                    "2021-08-14": 8536.230144,
                    "2021-08-06": 8536.230144,
                    "2021-08-05": 0.0,
                    "2021-08-08": 8536.230144,
                    "2021-08-07": 8536.230144,
                    "2021-08-09": 8536.230144
                },
                "dateToTotalCost": {
                    "2021-08-11": 0.0,
                    "2021-08-10": 0.0,
                    "2021-08-13": 0.0,
                    "2021-08-12": 0.0,
                    "2021-08-04": 0.0,
                    "2021-08-14": 0.0,
                    "2021-08-06": 0.0,
                    "2021-08-05": 0.0,
                    "2021-08-08": 0.0,
                    "2021-08-07": 0.0,
                    "2021-08-09": 0.0
                },
                "total": 0.0,
                "currency": "CAD",
                "categories": [
                    {
                        "dateToTotalCost": {
                            "2021-08-11": 8536.230144,
                            "2021-08-10": 8536.230144,
                            "2021-08-13": 8536.230144,
                            "2021-08-12": 17072.460288,
                            "2021-08-04": 16572.460288,
                            "2021-08-14": 8536.230144,
                            "2021-08-06": 8536.230144,
                            "2021-08-05": 0.0,
                            "2021-08-08": 8536.230144,
                            "2021-08-07": 8536.230144,
                            "2021-08-09": 8536.230144
                        },
                        "total": 101934.76,
                        "adjustments": [
                            {
                                "itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                                "amount": -32831.65,
                                "dailyDeltas": {
                                    "2021-08-11": 2399.9712,
                                    "2021-08-10": 2399.9712,
                                    "2021-08-13": 2399.9712,
                                    "2021-08-12": 4799.9424,
                                    "2021-08-04": 4799.9424,
                                    "2021-08-14": 2399.9712,
                                    "2021-08-06": 2399.9712,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 2399.9712,
                                    "2021-08-07": 2399.9712,
                                    "2021-08-09": 2399.9712
                                },
                                "before": 164158.27,
                                "after": 131326.62,
                                "source": {
                                    "endDate": "2021-08-15",
                                    "subtype": "",
                                    "scope": "CATEGORIES",
                                    "typeString": "PERCENTAGE",
                                    "discount": {
                                        "applyToNewCustomersOnly": false,
                                        "discountedProducts": {},
                                        "type": "PERCENTAGE",
                                        "referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                        "subtype": "",
                                        "discountedCategories": {
                                            "950d5a79-f6df-4770-995a-5144e6feb6b0": 20
                                        },
                                        "scope": "CATEGORIES",
                                        "name": {
                                            "en": "compute-20-percent",
                                            "fr": "compute-20-percent"
                                        },
                                        "id": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                        "credit": false,
                                        "startDate": "2021-05-08T00:00:00Z"
                                    },
                                    "discountId": "6ee154d1-4318-47bb-bb18-2e605c227889",
                                    "type": "PERCENTAGE",
                                    "startDate": "2021-08-04",
                                    "referenceId": "6ee154d1-4318-47bb-bb18-2e605c227889"
                                },
                                "type": "PERCENTAGE"
                            },
                            {
                                "itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                                "amount": -28891.86,
                                "dailyDeltas": {
                                    "2021-08-11": 2111.974656,
                                    "2021-08-10": 2111.974656,
                                    "2021-08-13": 2111.974656,
                                    "2021-08-12": 4223.949312,
                                    "2021-08-04": 4223.949312,
                                    "2021-08-14": 2111.974656,
                                    "2021-08-06": 2111.974656,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 2111.974656,
                                    "2021-08-07": 2111.974656,
                                    "2021-08-09": 2111.974656
                                },
                                "before": 131326.62,
                                "after": 102434.76,
                                "source": {
                                    "endDate": "2021-08-15",
                                    "subtype": "",
                                    "scope": "ALL_PRODUCTS",
                                    "typeString": "PERCENTAGE",
                                    "discount": {
                                        "applyToNewCustomersOnly": false,
                                        "discountedProducts": {},
                                        "type": "PERCENTAGE",
                                        "packageDiscount": 22.0,
                                        "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                        "subtype": "",
                                        "discountedCategories": {},
                                        "scope": "ALL_PRODUCTS",
                                        "name": {
                                            "en": "discount",
                                            "fr": "escompte"
                                        },
                                        "id": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                        "credit": false,
                                        "startDate": "2021-05-08T00:00:00Z"
                                    },
                                    "discountId": "9b245d40-ba94-4e05-af51-89979d37fb29",
                                    "type": "PERCENTAGE",
                                    "startDate": "2021-08-04",
                                    "referenceId": "9b245d40-ba94-4e05-af51-89979d37fb29"
                                },
                                "type": "PERCENTAGE"
                            },
                            {
                                "itemId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                                "amount": -500.0,
                                "dailyDeltas": {
                                    "2021-08-04": 500.0
                                },
                                "before": 102434.76,
                                "after": 101934.76,
                                "source": {
                                    "endDate": "2021-08-15",
                                    "subtype": "",
                                    "scope": "CATEGORIES",
                                    "typeString": "CREDIT",
                                    "discount": {
                                        "applyToNewCustomersOnly": false,
                                        "discountedProducts": {},
                                        "type": "CREDIT",
                                        "referenceId": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0",
                                        "durationDays": 600,
                                        "subtype": "",
                                        "discountedCategories": {
                                            "950d5a79-f6df-4770-995a-5144e6feb6b0": 500
                                        },
                                        "scope": "CATEGORIES",
                                        "name": {
                                            "en": "compute-500-bucks",
                                            "fr": "compute-500-bucks"
                                        },
                                        "id": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0",
                                        "credit": true,
                                        "startDate": "2021-05-08T00:00:00Z"
                                    },
                                    "used": {
                                        "discountedCategories": {
                                            "950d5a79-f6df-4770-995a-5144e6feb6b0": -500.0
                                        }
                                    },
                                    "discountId": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0",
                                    "type": "CREDIT",
                                    "startDate": "2021-08-04",
                                    "remaining": {
                                        "discountedProducts": {},
                                        "discountedCategories": {
                                            "950d5a79-f6df-4770-995a-5144e6feb6b0": 500
                                        }
                                    },
                                    "referenceId": "85d5fc06-142a-4e04-9a27-2bf08b3c1be0"
                                },
                                "type": "CREDIT"
                            }
                        ],
                        "adjustmentAggregations": [
                            {
                                "scopedBefore": 164158.27,
                                "scopedAmount": -61723.51,
                                "subtype": "",
                                "before": 175678.27,
                                "cumulativeAmount": -73243.51,
                                "after": 102434.76,
                                "type": "PERCENTAGE",
                                "scopedAfter": 102434.76
                            },
                            {
                                "scopedBefore": 102434.76,
                                "scopedAmount": -500.0,
                                "subtype": "",
                                "before": 102434.76,
                                "cumulativeAmount": -500.0,
                                "after": 101934.76,
                                "type": "CREDIT",
                                "scopedAfter": 101934.76
                            }
                        ],
                        "name": {
                            "en": "compute",
                            "fr": "compute"
                        },
                        "subTotal": 102434.76,
                        "dateToSubTotalCost": {
                            "2021-08-11": 8536.230144,
                            "2021-08-10": 8536.230144,
                            "2021-08-13": 8536.230144,
                            "2021-08-12": 17072.460288,
                            "2021-08-04": 17072.460288,
                            "2021-08-14": 8536.230144,
                            "2021-08-06": 8536.230144,
                            "2021-08-05": 0.0,
                            "2021-08-08": 8536.230144,
                            "2021-08-07": 8536.230144,
                            "2021-08-09": 8536.230144
                        },
                        "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0",
                        "products": [
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 143998.27,
                                        "cumulativeAmount": -54143.35,
                                        "after": 89854.92,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "3c2bb895-4282-41a1-8db4-2269037dc561",
                                "usage": 7199.9136,
                                "pricingTiers": [],
                                "subTotal": 89854.92,
                                "dateToSubTotalCost": {
                                    "2021-08-11": 7487.910144,
                                    "2021-08-10": 7487.910144,
                                    "2021-08-13": 7487.910144,
                                    "2021-08-12": 14975.820288,
                                    "2021-08-04": 14975.820288,
                                    "2021-08-14": 7487.910144,
                                    "2021-08-06": 7487.910144,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 7487.910144,
                                    "2021-08-07": 7487.910144,
                                    "2021-08-09": 7487.910144
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-08-11": 7487.910144,
                                    "2021-08-10": 7487.910144,
                                    "2021-08-13": 7487.910144,
                                    "2021-08-12": 14975.820288,
                                    "2021-08-04": 14975.820288,
                                    "2021-08-14": 7487.910144,
                                    "2021-08-06": 7487.910144,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 7487.910144,
                                    "2021-08-07": 7487.910144,
                                    "2021-08-09": 7487.910144
                                },
                                "total": 89854.92,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "20.000000",
                                "name": {
                                    "en": "storage",
                                    "fr": "storage"
                                },
                                "sku": "STORAGE",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [],
                                "adjustmentAggregations": [
                                    {
                                        "subtype": "",
                                        "before": 8640.0,
                                        "cumulativeAmount": -3248.64,
                                        "after": 5391.36,
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "productId": "6b94a874-9f85-4a14-9437-d5df30c8191d",
                                "usage": 288.0,
                                "pricingTiers": [],
                                "subTotal": 5391.36,
                                "dateToSubTotalCost": {
                                    "2021-08-11": 449.28,
                                    "2021-08-10": 449.28,
                                    "2021-08-13": 449.28,
                                    "2021-08-12": 898.56,
                                    "2021-08-04": 898.56,
                                    "2021-08-14": 449.28,
                                    "2021-08-06": 449.28,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 449.28,
                                    "2021-08-07": 449.28,
                                    "2021-08-09": 449.28
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-08-11": 449.28,
                                    "2021-08-10": 449.28,
                                    "2021-08-13": 449.28,
                                    "2021-08-12": 898.56,
                                    "2021-08-04": 898.56,
                                    "2021-08-14": 449.28,
                                    "2021-08-06": 449.28,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 449.28,
                                    "2021-08-07": 449.28,
                                    "2021-08-09": 449.28
                                },
                                "total": 5391.36,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "30.000000",
                                "name": {
                                    "en": "vm cpu",
                                    "fr": "vm cpu"
                                },
                                "sku": "VM_CPU",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            },
                            {
                                "adjustments": [
                                    {
                                        "itemId": "a36933e3-697a-4093-9057-18aed07479ea",
                                        "amount": -11520.0,
                                        "dailyDeltas": {
                                            "2021-08-11": 960.0,
                                            "2021-08-10": 960.0,
                                            "2021-08-13": 960.0,
                                            "2021-08-12": 1920.0,
                                            "2021-08-04": 1920.0,
                                            "2021-08-14": 960.0,
                                            "2021-08-06": 960.0,
                                            "2021-08-05": 0.0,
                                            "2021-08-08": 960.0,
                                            "2021-08-07": 960.0,
                                            "2021-08-09": 960.0
                                        },
                                        "before": 23040.0,
                                        "after": 11520.0,
                                        "source": {
                                            "endDate": "2021-08-15",
                                            "subtype": "",
                                            "scope": "PRODUCTS",
                                            "typeString": "PERCENTAGE",
                                            "discount": {
                                                "applyToNewCustomersOnly": false,
                                                "discountedProducts": {
                                                    "a36933e3-697a-4093-9057-18aed07479ea": 50
                                                },
                                                "type": "PERCENTAGE",
                                                "referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                                "subtype": "",
                                                "discountedCategories": {},
                                                "scope": "PRODUCTS",
                                                "name": {
                                                    "en": "vm-ram-50-percent",
                                                    "fr": "vm-ram-50-percent"
                                                },
                                                "id": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                                "credit": false,
                                                "startDate": "2021-05-08T00:00:00Z"
                                            },
                                            "discountId": "455feefb-0270-42ab-b9a1-ce87a430fd99",
                                            "type": "PERCENTAGE",
                                            "startDate": "2021-08-04",
                                            "referenceId": "455feefb-0270-42ab-b9a1-ce87a430fd99"
                                        },
                                        "type": "PERCENTAGE"
                                    }
                                ],
                                "adjustmentAggregations": [
                                    {
                                        "scopedBefore": 23040.0,
                                        "scopedAmount": -11520.0,
                                        "subtype": "",
                                        "before": 23040.0,
                                        "cumulativeAmount": -15851.52,
                                        "after": 7188.48,
                                        "type": "PERCENTAGE",
                                        "scopedAfter": 11520.0
                                    }
                                ],
                                "productId": "a36933e3-697a-4093-9057-18aed07479ea",
                                "usage": 576.0,
                                "pricingTiers": [],
                                "subTotal": 7188.48,
                                "dateToSubTotalCost": {
                                    "2021-08-11": 599.04,
                                    "2021-08-10": 599.04,
                                    "2021-08-13": 599.04,
                                    "2021-08-12": 1198.08,
                                    "2021-08-04": 1198.08,
                                    "2021-08-14": 599.04,
                                    "2021-08-06": 599.04,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 599.04,
                                    "2021-08-07": 599.04,
                                    "2021-08-09": 599.04
                                },
                                "taxCode": "SW056003",
                                "dateToTotalCost": {
                                    "2021-08-11": 599.04,
                                    "2021-08-10": 599.04,
                                    "2021-08-13": 599.04,
                                    "2021-08-12": 1198.08,
                                    "2021-08-04": 1198.08,
                                    "2021-08-14": 599.04,
                                    "2021-08-06": 599.04,
                                    "2021-08-05": 0.0,
                                    "2021-08-08": 599.04,
                                    "2021-08-07": 599.04,
                                    "2021-08-09": 599.04
                                },
                                "total": 7188.48,
                                "unit": {
                                    "unit": "HOUR",
                                    "name": {}
                                },
                                "price": "40.000000",
                                "name": {
                                    "en": "ram",
                                    "fr": "ram"
                                },
                                "sku": "VM_RAM",
                                "categoryId": "950d5a79-f6df-4770-995a-5144e6feb6b0"
                            }
                        ]
                    }
                ],
                "startDate": "2021-08-04T00:00:00Z"
            },
            "status": "ISSUED"
        }
    ]
}

Attributes
id UUID	The UUID of the invoice.
invoiceId string	The human readable id.
status enum	The status of the invoice. Possible values are: USAGE_PENDING, IN_REVIEW, ISSUED, OVERDUE, PAID, VOID.
createdDate date	The created date of the invoice.
draftedDate date	The date the invoice was drafted. Is null if status is still USAGE_PENDING.
issuedDate date	The date the invoice was issued.
dueDate date	The date the invoice is due.
organization.id UUID	The UUID of the organization the invoice belongs to.
organization.name string	The name of the organization the invoice belongs to.
balance BigDecimal	The invoice's remaining balance.
detail Object	The invoice detail contains a currency and a list of categories. Each category has a list of products.
detail.currency string	The short-name of the currency.
detail.subTotal string	A string containing the total before taxes and credits.
detail.total string	The invoice total after discounts, taxes, and credits.
detail.startDate string	An ISO-8601 instant format string representing the start of the invoice detail report.
detail.endDate string	An ISO-8601 instant format string representing the end of the invoice detail report.
detail.adjustments Array[Object]	The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax.
detail.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.adjustments.amount string	The adjustment amount applied to the invoice total.
detail.adjustments.before string	The invoice total before the adjustment was applied.
detail.adjustments.after string	The invoice total after the adjustment was applied.
detail.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.adjustmentAggregations.before string	The invoice total before the adjustments were applied.
detail.adjustmentAggregations.after string	The invoice total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.adjustmentAggregations.cumulativeAmount string	The cumulative adjustment amount applied to the invoice, its categories and their products.
detail.categories Array[Object]	An array of category objects. Contains all categories that had usage for the period.
detail.categories.name Object	A map of short language codes to their translated category names.
detail.categories.subTotal string	A string with the category subtotal, before taxes and credits.
detail.categories.total string	A string with the category subtotal, after taxes and credits.
detail.adjustments Array[Object]	The adjustments applied to the category. An adjustment tracks the application of a discount, a credit or a tax.
detail.categories.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.adjustments.itemId UUID	The category id.
detail.categories.adjustments.amount string	The adjustment amount applied to the category total.
detail.categories.adjustments.before string	The category total before the adjustment was applied.
detail.categories.adjustments.after string	The category total after the adjustment was applied.
detail.categories.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.categories.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.categories.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.categories.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.adjustmentAggregations.before string	The category total before the adjustments were applied.
detail.categories.adjustmentAggregations.after string	The category total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.adjustmentAggregations.cumulativeAmount string	The cumulative adjustment amount applied to the category and its products.
detail.categories.products Object	A map of short language codes to their translated category names.
detail.categories.products.sku string	A unique string representing the sku for a product.
detail.categories.products.name Object	The name object in each language for the product name.
detail.categories.products.cost string	A string of the summed up total cost for the product.
detail.categories.products.usage Object	A string of the summed up total usage for the product.
detail.categories.products.price Object	A string representing the average unit price over the period.
detail.categories.products.subTotal string	A string with the product subtotal, before taxes and credits.
detail.categories.products.total string	A string with the product total, after taxes and credits.
detail.categories.products.period string	The period for the product capture. Possible values: HOURS, MONTH.
detail.categories.products.unit Object	The unit object of the product.
detail.categories.products.unit.unit Object	The unit value of the product.
detail.categories.products.unit.name Object	The name of the unit of the product in the required language. Only present when defining custom units.
detail.categories.products.adjustments Array[Object]	The adjustments applied to the invoice. An adjustment tracks the application of a discount, a credit or a tax.
detail.categories.products.adjustments.type string	The type of adjustment. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.products.adjustments.itemId UUID	The product id.
detail.categories.products.adjustments.amount string	The adjustment amount applied to the product total.
detail.categories.products.adjustments.before string	The product total before the adjustment was applied.
detail.categories.products.adjustments.after string	The product total after the adjustment was applied.
detail.categories.products.adjustments.dailyDeltas Object	A map of the local date to the change in daily cost due to the adjustment.
detail.categories.products.adjustments.source Object	The model of the adjustment. Can be a discount or a tax model.
detail.categories.products.adjustmentAggregations Array[Object]	The adjustment aggregations. An aggregation summarizes the application of discounts, taxes or credits.
detail.categories.products.adjustmentAggregations.type string	The type of adjustment being aggregated. Possible values are: PERCENTAGE, CREDIT, TAX.
detail.categories.products.adjustmentAggregations.subtype string	The optional type used for sub-aggregations, like tax breakdowns.
detail.categories.products.adjustmentAggregations.scopedAmount string	The adjustment amount applied to the product total. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.scopedBefore string	The product total before the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.before string	The product total before the adjustments were applied.
detail.categories.products.adjustmentAggregations.scopedAfter string	The product total after the adjustments were applied. Only includes adjustments with the same scope as the item.
detail.categories.products.adjustmentAggregations.after string	The product total after the adjustments were applied.
detail.categories.products.adjustmentAggregations.cumulativeAmount string	The adjustment amount applied to the product total.

Download invoice

GET /invoices/download?invoice_id=:invoice_id

Download an invoice as a PDF file.

# Download an invoice
curl  -X GET 'https://cloudmc_endpoint/rest/invoices/download?invoice_id=3f7b7cca-d440-4c70-8ea7-ff23fe88b152' \
  -H 'MC-Api-Key: your_api_key'

Required
invoice_id UUID	The id of the invoice.

Payments

Retreive the history of payment transactions for an organization.

List payments

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/payments?organizationId=07d88499-a17f-4a68-8888-bbec953xxx1d"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "paymentTraceReference": "925613851809199",
      "paymentReference": "20210930033702-qfm04yt",
      "totalAmount": 5338.72,
      "confirmationNumber": "6155D9A173DE0841F48B291C2A24BE80AFB153CD",
      "deleted": false,
      "id": "07d88499-a17f-4a68-8560-bbec953cec1d",
      "invoice": {
        "createdDate": "2021-09-01T14:21:11Z",
        "invoiceId": "91438A1596",
        "id": "6f34d8a4-6256-4e43-96a9-6bfde2b21585"
      },
      "paymentDate": "2021-10-12T17:34:53Z",
      "taxAmount": 253.0,
      "currencyCode": "CAD",
      "status": "SUCCESS",
      "extraInfo": {
        "approvalStatus": "1",
        "procStatus": "0",
        "procStatusMessage": "Approved",
        "respCodeMessage": "",
        "respCode": "00"
      }
    },
    {
      "paymentTraceReference": "925613851809132",
      "paymentReference": "20210930033702-qfm032D",
      "errorMsg": "Transport error: 412 Error: Precondition Failed",
      "totalAmount": 5338.72,
      "confirmationNumber": "6155D9A173DE0841F48B291C2A24BE80AFB153WE",
      "id": "a8139387-b286-49e4-a458-afbaf1c604f7",
      "invoice": {
        "createdDate": "2021-09-01T14:21:11Z",
        "invoiceId": "91438A1596",
        "id": "6f34d8a4-6256-4e43-96a9-6bfde2b21585"
      },
      "paymentDate": "2021-10-11T17:34:50Z",
      "taxAmount": 1.0,
      "currencyCode": "USD",
      "status": "FAIL"
    }
  ]
}

GET /payments?organizationId=:orgId

Retrieve a list of payment processed for an organization.

Query Params
organizationId UUID	The ID of the organization for which we want to see the payments.

Attributes
id UUID	A payment's unique identifier.
invoice Object	The invoice associated to the payment.
invoice.id UUID	The UUID of the invoice.
invoice.invoiceId String	The human readable invoice id.
invoice.createdDate date	The created date of the invoice.
paymentReference String	Payment reference sent to the payment provider to indentify the transaction.
paymentTraceReference String	Additional reference used to find a payment on the payment provider side.
errorMsg String	The error message returned by the payment provider if the payment failed.
totalAmount BigDecimal	The total amount of the invoice charged on the card.
taxAmount BigDecimal	The tax amount that was included in the charge.
confirmationNumber String	Confirmation number returned from the payment provider.
paymentDate date	The date on which the payment was sent to the provider.
currencyCode String	The currency of the payment.
status String	Status of the payment. One of SUCCESS, PENDING, FAIL.
extraInfo String	Additional information set in the payment transaction.

Retrieve a payment

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/payments/07d88499-a17f-4a68-8560-bbec953ert1d"

The above command returns a JSON structured like this:

{
  "data": {
    "paymentTraceReference": "925613851809199",
    "paymentReference": "20210930033702-qfm04yt",
    "totalAmount": 5338.72,
    "confirmationNumber": "6155D9A173DE0841F48B291C2A24BE80AFB153CD",
    "id": "07d88499-a17f-4a68-8560-bbec953ert1d",
    "invoice": {
      "createdDate": "2021-09-01T14:21:11Z",
      "invoiceId": "91438A1596",
      "id": "6f34d8a4-6256-4e43-96a9-6bfde2b21585"
    },
    "paymentDate": "2021-10-12T17:34:53Z",
    "taxAmount": 253.0,
    "currencyCode": "CAD",
    "status": "SUCCESS",
    "extraInfo": {
      "approvalStatus": "1",
      "procStatus": "0",
      "procStatusMessage": "Approved",
      "respCodeMessage": "",
      "respCode": "00"
    }
  }
}

GET /payments/:id

Retrieve a payment.

Attributes
id UUID	A payment's unique identifier.
invoice Object	The invoice associated to the payment.
invoice.id UUID	The UUID of the invoice.
invoice.invoiceId String	The human readable invoice id.
invoice.createdDate date	The created date of the invoice.
paymentReference String	Payment reference sent to the payment provider to indentify the transaction.
paymentTraceReference String	Additional reference used to find a payment on the payment provider side.
errorMsg String	The error message returned by the payment provider if the payment failed.
totalAmount BigDecimal	The total amount of the invoice charged on the card.
taxAmount BigDecimal	The tax amount that was included in the charge.
confirmationNumber String	Confirmation number returned from the payment provider.
paymentDate date	The date on which the payment was sent to the provider.
currencyCode String	The currency of the payment.
status String	Status of the payment. One of SUCCESS, PENDING, FAIL.
extraInfo String	Additional information set in the payment transaction.

Discounts

The discount allows the assignment of a percentage discount or credit to an applied pricing.

List discounts

GET /applied_pricings/:applied_pricing_id/discounts?type=:type

Retrieve the list of discounts associated with an applied pricing.

# Retrieve applied pricing list
curl "https://cloudmc_endpoint/rest/applied_pricings/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts?type=PERCENTAGE" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "applyToNewCustomersOnly": true,
      "discountedProducts": {},
      "durationDays": 60,
      "type": "PERCENTAGE",
      "packageDiscount": 20.0,
      "discountScope": "ALL_PRODUCTS",
      "isDeactivated": true,
      "discountedCategories": {},
      "name": {
        "en": "Summer Discount",
        "fr": "Réduction Estival"
      },
      "id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
      "appliedPricing": {
        "id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
      },
      "startDate": "2021-07-20T15:57:16.132Z",
      "status": "CURRENT"
    }
  ]
}

Optional Query Parameters
type enum	The type of the discount. It could be either "PERCENTAGE" or "CREDIT".

Attributes
id UUID	The UUID of the discount.
discountedProducts Map[UUID, BigDecimal]	A mapping of the desired priced product IDs and discounts. All pricing products specified will have the discount value applied to them.
durationDays integer	Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached.
type enum	The type of the discount. It could be either "PERCENTAGE" or "CREDIT".
packageDiscount BigDecimal	The discount value that will be applied to all products within the applied pricing.
discountScope enum	The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS".
isDeactivated boolean	Whether or not the discount is deactivated. Defaults to false.
discountedCategories Map[UUID, BigDecimal]	A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them.
name Map[String, String]	The name translations of the discount.
appliedPricing Object	The applied pricing being discounted.
appliedPricing.id UUID	The UUID of the applied pricing.
applyToNewCustomersOnly boolean	If true, the discount will only be applied to organizations created after the discount start date.
startDate date	The start date of the discount.
cutoffDate date	The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date.
status enum	The status of the discount. Possible values are: UPCOMING, CURRENT, ENDED.

Get discount

GET /applied_pricings/:applied_pricing_id/discounts/:id

Retrieve a discount's details.

# Retrieve applied pricing list
curl "https://cloudmc_endpoint/rest/applied_pricings/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "applyToNewCustomersOnly": true,
      "discountedProducts": {},
      "durationDays": 60,
      "type": "PERCENTAGE",
      "packageDiscount": 20.0,
      "discountScope": "ALL_PRODUCTS",
      "isDeactivated": true,
      "discountedCategories": {},
      "name": {
        "en": "Summer Discount",
        "fr": "Réduction Estival"
      },
      "id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
      "appliedPricing": {
        "id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
      },
      "startDate": "2021-07-20T15:57:16.132Z",
      "status": "CURRENT"
    }
  ]
}

Attributes
id UUID	The UUID of the discount.
discountedProducts Map[UUID, BigDecimal]	A mapping of the desired priced product IDs and discounts. All pricing products specified will have the discount value applied to them.
durationDays integer	Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached.
type enum	The type of the discount. It could be either "PERCENTAGE" or "CREDIT".
packageDiscount BigDecimal	The discount value that will be applied to all products within the applied pricing.
discountScope enum	The scope of the discount. It could be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS".
isDeactivated boolean	Whether or not the discount is deactivated. Defaults to false.
discountedCategories Map[UUID, BigDecimal]	A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them.
name Map[String, String]	The name translations of the discount.
appliedPricing Object	The applied pricing being discounted.
appliedPricing.id UUID	The UUID of the applied pricing.
applyToNewCustomersOnly boolean	If true, the discount will only be applied to organizations created after the discount start date.
startDate date	The start date of the discount.
cutoffDate date	The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date.
status enum	The status of the discount. Possible values are: UPCOMING, CURRENT, ENDED.

Create discount

POST /applied_pricings/:applied_pricing_id/discounts

Create a new discount

# Creates a new discount
curl -X POST "https://cloudmc_endpoint/rest/applied_pricings/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": {
    "en": "Summer Discount",
    "fr": "Réduction Estival"
  },
  "startDate": "2021-07-23T00:00:00.000Z",
  "type": "PERCENTAGE",
  "durationDays": 60,
  "discountedProducts": {},
  "discountedCategories": {
    "8cf73cc0-b86e-49b4-a102-6102894f7955": 2, 
    "00358632-5c9a-4164-a9a9-df271a9c06a9": 22
  },
  "discountScope": "CATEGORIES", 
  "cutoffDate": "2021-07-24T00:00:00.000Z",
  "applyToNewCustomersOnly": false,
}

The above command returns a JSON structured like this:

{
  "data": {
      "applyToNewCustomersOnly": false,
      "discountedProducts": {},
      "durationDays": 60,
      "type": "PERCENTAGE",
      "discountScope": "CATEGORIES",
      "discountedCategories": {
        "8cf73cc0-b86e-49b4-a102-6102894f7955": 2, 
        "00358632-5c9a-4164-a9a9-df271a9c06a9": 22
      },  
      "name": {
        "en": "Summer Discount",
        "fr": "Réduction Estival"
      },
      "id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
      "appliedPricing": {
        "id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
      },
      "startDate": "2021-07-23T00:00:00.000Z",
      "cutoffDate": "2021-07-24T00:00:00.000Z",
  }
}

Required
name Map[String, String]	The name translations of the discount.
type enum	The type of the discount. It can be either "PERCENTAGE" or "CREDIT".
startDate date	The start date of the discount.
applyToNewCustomersOnly boolean	If true, the discount will only be applied to organizations created after the discount start date.
discountScope enum	The scope of the discount. It can be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS".
packageDiscount BigDecimal	The discount value that will be applied to all products within the applied pricing. Only required if the scope is "ALL_PRODUCTS". The value must be between (0,100] for a percentage discount and greater than 0 for a credit.
discountedCategories Map[UUID, BigDecimal]	A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. Required to be non-empty if scope is "CATEGORIES". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit.
discountedProducts Map[UUID, BigDecimal]	A mapping of the desired priced product IDs and discount values. All pricing products specified will have the discount value applied to them. Required to be non-empty if scope is "PRODUCTS". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit.

Optional
cutoffDate date	The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date.
durationDays integer	Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached.

Edit discount

PUT /applied_pricings/:applied_pricing_id/discounts/:id

Edit an existing discount that hasn't ended. Only the name and cutoff date can be edited for current discount. All fields can be edited for upcoming discounts.

# Edit an existing discount
curl -X PUT "https://cloudmc_endpoint/rest/applied_pricings/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": {
    "en": "End of summer Discount",
    "fr": "Réduction estival fin d'été"
  },
  "durationDays": 60,
  "discountedProducts": {},
  "discountedCategories": {
    "8cf73cc0-b86e-49b4-a102-6102894f7955": 2, 
    "00358632-5c9a-4164-a9a9-df271a9c06a9": 22
  },
  "discountScope": "CATEGORIES", 
  "cutoffDate": "2021-08-24T00:00:00.000Z",
  "applyToNewCustomersOnly": false,
}

The above command returns a JSON structured like this:

{
  "data": {
      "applyToNewCustomersOnly": false,
      "discountedProducts": {},
      "durationDays": 60,
      "type": "PERCENTAGE",
      "discountScope": "CATEGORIES",
      "discountedCategories": {
        "8cf73cc0-b86e-49b4-a102-6102894f7955": 2, 
        "00358632-5c9a-4164-a9a9-df271a9c06a9": 22
      },  
      "name": {
        "en": "End of summer Discount",
        "fr": "Réduction estival fin d'été"
      },
      "id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
      "appliedPricing": {
        "id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
      },
      "startDate": "2021-07-23T00:00:00.000Z",
      "cutoffDate": "2021-08-24T00:00:00.000Z",
      "status": "UPCOMING"
  }
}

Optional
name Map[String, String]	The name translations of the discount.
startDate date	The start date of the discount.
applyToNewCustomersOnly boolean	If true, the discount will only be applied to organizations created after the discount start date.
discountScope enum	The scope of the discount. It can be either "ALL_PRODUCTS", "CATEGORIES" or "PRODUCTS".
packageDiscount BigDecimal	The discount value that will be applied to all products within the applied pricing. Only required if the scope is "ALL_PRODUCTS". The value must be between (0,100] for a percentage discount and greater than 0 for a credit.
discountedCategories Map[UUID, BigDecimal]	A mapping between category IDs and discount values. All pricing products within a category will have the discount value applied to them. Required to be non-empty if scope is "CATEGORIES". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit.
discountedProducts Map[UUID, BigDecimal]	A mapping of the desired priced product IDs and discount values. All pricing products specified will have the discount value applied to them. Required to be non-empty if scope is "PRODUCTS". All discount values must be between (0,100] for a percentage discount and greater than 0 for a credit.
cutoffDate date	The date on which the discount will no longer be offered to customers who have not already received it. If not provided, the discount will always be offered after the start date.
durationDays integer	Duration of the discount once it has been applied to a customer. If not provided the discount will last indefinitely, or until credit values are reached.

Delete discount

DELETE /applied_pricings/:applied_pricing_id/discounts/:id

Delete a discount. This operation can only be performed on discounts that have status UPCOMING.

curl -X DELETE "https://cloudmc_endpoint/rest/applied_pricings/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
  "taskStatus": "SUCCESS"
}

Deactivate discount

PUT /applied_pricings/:applied_pricing_id/discounts/:id/deactivate

Deactivate a discount. This operation can only be performed on discounts that have status CURRENT or ENDED. Deactivated is a final state, cannot be reactivated.

curl -X PUT "https://cloudmc_endpoint/rest/applied_pricings/efd32752-c6f2-45cf-b494-cc6be8a45845/discounts/18db7bc6-8be1-48bb-bab1-77a7d696fa3b/deactivate" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
      "applyToNewCustomersOnly": false,
      "discountedProducts": {},
      "durationDays": 60,
      "type": "PERCENTAGE",
      "discountScope": "CATEGORIES",
      "isDeactivated": true,
      "discountedCategories": {
        "8cf73cc0-b86e-49b4-a102-6102894f7955": 2, 
        "00358632-5c9a-4164-a9a9-df271a9c06a9": 22
      },  
      "name": {
        "en": "End of summer Discount",
        "fr": "Réduction estival fin d'été"
      },
      "id": "18db7bc6-8be1-48bb-bab1-77a7d696fa3b",
      "appliedPricing": {
        "id": "efd32752-c6f2-45cf-b494-cc6be8a45845"
      },
      "startDate": "2020-07-23T00:00:00.000Z",
      "cutoffDate": "2020-08-24T00:00:00.000Z",
      "status": "ENDED"
  }
}

Authentication

Identity providers

Configure methods of authentication for your organizations.

List identity providers

GET /identity_providers

# Retrieve identity providers
curl "https://cloudmc_endpoint/api/v1/identity_providers" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [{
      "provider": "GOOGLE",
      "displayName": "Google",
      "logo": "aHR0cHM6Ly9kZXZlbG9wZXJzLmdvb2dsZS5jb20vaWR23nRpdHkvaW1hZ2VzL2ctbG9nby5wbmc=",
      "identityProviderUsers": [
        {
          "user": {
            "id": "0c4hc34e-ff76-48de-8976-7cb2fc89aa96"
          },
          "subjectId": "totallyFakeSubjectID"
        }
      ],
      "id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceae5",
      "connectionName": "Google",
      "type": "OIDC",
      "rank": "1",
      "parameters": [
        {
          "parameter": "issuerURL",
          "id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceab1",
          "value": "https://accounts.google.com"
        },
        {
          "parameter": "clientSecret",
          "id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceab3",
          "value": "sssshhhhhhhhh"
        },
        {
          "parameter": "clientID",
          "id": "02b3cbd5-9286-4cd7-b47e-22b2fb9ceab4",
          "value": "shhhID"
        }
      ]
    }]
}

List the identity providers configured on the system.

Attributes
id UUID	The id of the identity provider.
provider string	The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider.
displayName string	The display name of the identity provider that will appear on the login screen.
logo string	A base64 encoded data URL or URL to an image for the logo to display on the login screen.
css string	Custom css for the login button of the identity provider.
identityProviderUsers Array	A list of objects containing the ids of users associated with the identity provider, and their subject ids.
connectionName string	The connection name of the identity provider.
type string	The type of authentication protocol. Possible values: OIDC, SAML.
parameters Array	A list of parameters associated with the identity provider.
rank int	If provided, this integer sorts identity providers on the Login page in ascending order.

Create identity provider

POST /identity_providers

Create a new identity provider.

# Creates a new identity provider
curl -X POST "https://cloudmc_endpoint/rest/identity_providers" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
    "provider": "CUSTOM",
    "type": "OIDC",
    "connectionName": "CloudMC Google",
    "displayName": "Google",
    "parameters": [
        {
            "parameter": "issuerURL",
            "value": "https://accounts.google.com"
        },
        {
            "parameter": "clientId",
            "value": "secret"
        },
        {
            "parameter": "clientSecret",
            "value": "secret"
        }
    ]
}

The above command return JSON structured like this:

{
  "data": {
    "provider": "CUSTOM",
    "displayName": "Google",
    "connectionName": "CloudMC Google",
    "type": "OIDC",
    "rank": "1",
    "parameters": [
      {
        "parameter": "issuerURL",
        "id": "54d423fc-5ae2-4abc-bca6-9325376b6275",
        "value": "https://accounts.google.com"
      },
      {
        "parameter": "clientId",
        "id": "a0538e7e-3049-45f0-97a5-83f55fc012e9",
        "value": "secret"
      },
      {
        "parameter": "clientSecret",
        "id": "760c6c03-7c2f-4a18-a7c8-9ebc758ea33e",
        "value": "secret"
      }
    ]
  }
}

Required
id UUID	The id of the identity provider.
provider string	The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider.
displayName string	The display name of the identity provider that will appear on the login screen. If of a default provider type, this will be set with a default if not passed.
connectionName string	The connection name of the identity provider. If of a default provider type, this will be set with a default if not passed.
logo string	A base64 encoded data URL or URL to an image for the logo to display on the login screen. If of a default provider type, this will be set with a default if not passed.
type string	The type of authentication protocol. Possible values: OIDC, SAML.
parameters Array	A list of parameters associated with the identity provider. The issuerURL will be set if of a default provider type.
rank int	If provided, this integer sorts identity providers on the Login page in ascending order.

Optional
css string	Custom css for the login button of the identity provider.

Update Identity Provider

PUT /identity_providers/:id

Update an existing identity provider.

# Updates an existing identity provider
curl -X PUT "https://cloudmc_endpoint/rest/identity_providers/c84cfe41-929b-47c9-bde4-b55a10bd2774" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
    "provider": "CUSTOM",
    "type": "OIDC",
    "id": "c84cfe41-929b-47c9-bde4-b55a10bd2774",
    "connectionName": "CloudMC Google",
    "displayName": "Google",
    "parameters": [
        {
            "parameter": "issuerURL",
            "value": "https://accounts.google.com"
        },
        {
            "parameter": "clientId",
            "value": "secret"
        },
        {
            "parameter": "clientSecret",
            "value": "secret"
        }
    ]
}

The above command return JSON structured like this:

{
  "data": {
    "provider": "CUSTOM",
    "displayName": "Google",
    "id": "da33bf85-6ba3-4214-a258-9442de149eff",
    "connectionName": "CloudMC Google",
    "type": "OIDC",
    "rank": "1",
    "parameters": [
      {
        "parameter": "issuerURL",
        "id": "54d423fc-5ae2-4abc-bca6-9325376b6275",
        "value": "https://accounts.google.com"
      },
      {
        "parameter": "clientId",
        "id": "a0538e7e-3049-45f0-97a5-83f55fc012e9",
        "value": "secret"
      },
      {
        "parameter": "clientSecret",
        "id": "760c6c03-7c2f-4a18-a7c8-9ebc758ea33e",
        "value": "secret"
      }
    ]
  }
}

Required
id UUID	The id of the identity provider.
provider string	The name of the provider. Possible values include the default providers (e.g GOOGLE), or CUSTOM for a custom user-defined provider.
displayName string	The display name of the identity provider that will appear on the login screen. If of a default provider type, this will be set with a default if not passed.
connectionName string	The connection name of the identity provider. If of a default provider type, this will be set with a default if not passed.
logo string	A base64 encoded data URL or URL to an image for the logo to display on the login screen. If of a default provider type, this will be set with a default if not passed.
type string	The type of authentication protocol. Possible values: OIDC, SAML.
parameters Array	A list of parameters associated with the identity provider. The issuerURL will be set if of a default provider type.
rank int	If provided, this integer sorts identity providers on the Login page in ascending order.

Optional
css string	Custom css for the login button of the identity provider.

Delete Identity Provider

Delete /identity_providers/:id

Delete an existing identity provider.

# Deletes a specified identity provider
curl -X DELETE "https://cloudmc_endpoint/rest/identity_providers/c84cfe41-929b-47c9-bde4-b55a10bd2774" \
   -H "MC-Api-Key: your_api_key"

The above command(s) return(s) JSON structured like this:

{
  "taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
  "taskStatus": "SUCCESS"
}

Attributes
taskId string	The task id related to the identity provider deletion.
taskStatus string	The status of the operation.

Service Providers

Configure the service providers that can use CloudMC as their authentication source.

List service providers

GET /service_providers?organization_id=:organization_id

# Retrieve service providers
curl "https://cloudmc_endpoint/api/v1/service_providers?organization_id=:organization_id" \
   -H "MC-Api-Key: your_api_key"

Optional query parameters
organization_id string	The organization whose SAML settings are to be retrieved. If this is not provided then the request defaults to the user's organization.

The above command returns JSON structured like this:

{
  "data": [
    {
      "name": "Slack",
      "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
      "type": "SAML",
      "config": {
        "assertionConsumerUrl": "issuer.com",
        "nameIdFormat": "UNSPECIFIED",
        "responseAttributes": [
          {
            "nameFormat": "UNSPECIFIED",
            "attributeName": "username",
            "attributeValueField": {
              "fieldName": "firstName",
              "sourceModel": "user"
            }
          }
        ],
        "sign": "RESPONSE",
        "serviceProviderIssuer": "slack"
      },
      "organization": {
        "id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
      }
    }
  ]
}

List the service providers of an organization

Attributes
id UUID	The id of the service provider.
name string	The name of the service provider.
type string	The type of service provider. Possible values are : SAML.
config Object	The object containing the configuration of the service provider.
config.serviceProviderIssuer string	The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL.
config.assertionConsumerUrl string	The URL where the response is sent.
config.sign string	How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE.
config.nameIdFormat string	The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT.
config.responseAttributes Array[Object]	The list of attributes part of the response
config.responseAttributes.nameFormat string	The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC.
config.responseAttributes.attributeName string	The attribute name
config.responseAttributes.attributeValueField Object	The object containing the source for the value in the response.
config.responseAttributes.attributeValueField.sourceModel string	The model object to get the value from. Possible values are : ORGANIZATION, USER.
config.responseAttributes.attributeValueField.fieldName string	The field name to get the information from.
organization Organization	The organization tied to the service provider.

Retrieve service provider

GET /service_providers/:id

# Retrieve service providers
curl "https://cloudmc_endpoint/api/v1/service_providers/:id" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "name": "Slack",
    "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
    "type": "SAML",
    "config": {
      "assertionConsumerUrl": "issuer.com",
      "nameIdFormat": "UNSPECIFIED",
      "responseAttributes": [
        {
          "nameFormat": "UNSPECIFIED",
          "attributeName": "username",
          "attributeValueField": {
            "fieldName": "firstName",
            "sourceModel": "user"
          }
        }
      ],
      "sign": "RESPONSE",
      "serviceProviderIssuer": "slack"
    },
    "organization": {
      "id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
    }
  }
}

Return the service provider configured associated to the id on the system.

Attributes
id UUID	The id of the service provider.
name string	The name of the service provider.
type string	The type of service provider. Possible values are : SAML.
config Object	The object containing the configuration of the service provider.
config.serviceProviderIssuer string	The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL.
config.assertionConsumerUrl string	The URL where the response is sent.
config.sign string	How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE.
config.nameIdFormat string	The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT.
config.responseAttributes Array[Object]	The list of attributes part of the response
config.responseAttributes.nameFormat string	The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC.
config.responseAttributes.attributeName string	The attribute name
config.responseAttributes.attributeValueField Object	The object containing the source for the value in the response.
config.responseAttributes.attributeValueField.sourceModel string	The model object to get the value from. Possible values are : ORGANIZATION, USER.
config.responseAttributes.attributeValueField.fieldName string	The field name to get the information from.
organization Organization	The organization tied to the service provider.

Create service provider

POST /service_providers

# Creates a new service provider
curl -X POST "https://cloudmc_endpoint/api/v1/service_providers" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": "Slack",
  "type": "SAML",
  "config": {
    "assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
    "serviceProviderIssuer": "https://slack.com",
    "sign": "RESPONSE",
    "responseAttributes": [
      {
        "attributeName": "first-name",
        "attributeValueField": {
          "sourceModel": "user",
          "fieldName": "firstName"
        }
      }
    ]
  },
  "organization": {
    "id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
  }
}

The above command return JSON structured like this:

{
  "data": {
    "name": "Slack",
    "id": "dbf3df1c-d28e-4cb5-bcb9-ce85d1675b27",
    "type": "SAML",
    "config": {
      "assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
      "nameIdFormat": "UNSPECIFIED",
      "responseAttributes": [
        {
          "nameFormat": "UNSPECIFIED",
          "attributeName": "first-name",
          "attributeValueField": {
            "fieldName": "firstName",
            "sourceModel": "user"
          }
        }
      ],
      "name": "Slack",
      "sign": "RESPONSE",
      "serviceProviderIssuer": "https://slack.com"
    },
    "organization": {
      "id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
    }
  }
}

Create a new service provider

Required
name string	The name of the service provider.
type string	The type of service provider. Possible values are : SAML.
config Object	The object containing the configuration of the service provider.
config.serviceProviderIssuer string	The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL.
config.assertionConsumerUrl string	The URL where the response is sent.
config.sign string	How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeName string	The attribute name. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeValueField Object	The object containing the source for the value in the response. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeValueField.sourceModel string	The model object to get the value from. Possible values are : ORGANIZATION, USER. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeValueField.fieldName string	The field name to get the information from. Only required if config.responseAttributes is passed.
organization Organization	The organization tied to the service provider.

Optional
config.nameIdFormat string	The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT. If not provided this defaults to UNSPECIFIED.
config.responseAttributes.nameFormat string	The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC. If not provided this defaults to UNSPECIFIED.
config.responseAttributes Array[Object]	The list of attributes part of the response.

Update service provider

PUT /service_providers/:id

# Updates an existing service provider
curl -X PUT "https://cloudmc_endpoint/api/v1/service_providers/:id" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": "Slack",
  "id": "dbf3df1c-d28e-4cb5-bcb9-ce85d1675b27",
  "type": "SAML",
  "config": {
    "assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
    "serviceProviderIssuer": "https://slack.com",
    "sign": "RESPONSE",
    "responseAttributes": [
      {
        "attributeName": "first-name",
        "attributeValueField": {
          "sourceModel": "user",
          "fieldName": "firstName"
        }
      }
    ]
  },
  "organization": {
    "id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
  }
}

The above command return JSON structured like this:

{
  "data": {
    "name": "Slack",
    "id": "dbf3df1c-d28e-4cb5-bcb9-ce85d1675b27",
    "type": "SAML",
    "config": {
      "assertionConsumerUrl": "https://yourdomain.slack.com/sso/saml",
      "nameIdFormat": "UNSPECIFIED",
      "responseAttributes": [
        {
          "nameFormat": "UNSPECIFIED",
          "attributeName": "first-name",
          "attributeValueField": {
            "fieldName": "firstName",
            "sourceModel": "user"
          }
        }
      ],
      "name": "Slack",
      "sign": "RESPONSE",
      "serviceProviderIssuer": "https://slack.com"
    },
    "organization": {
      "id": "976e1d4b-de6f-454b-a189-b12dd1b85112"
    }
  }
}

Updates a specific service provider

Required
name string	The name of the service provider.
type string	The type of service provider. Possible values are : SAML.
config Object	The object containing the configuration of the service provider.
config.serviceProviderIssuer string	The issuer for the service provider. This is what is contained in the SAML request issuer tag. This is also referred to as the EntityID or EntityURL.
config.assertionConsumerUrl string	The URL where the response is sent.
config.sign string	How the returned XML is signed. Possible values are : ASSERTION, RESPONSE, ASSERTION_AND_RESPONSE. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeName string	The attribute name. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeValueField Object	The object containing the source for the value in the response. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeValueField.sourceModel string	The model object to get the value from. Possible values are : ORGANIZATION, USER. Only required if config.responseAttributes is passed.
config.responseAttributes.attributeValueField.fieldName string	The field name to get the information from. Only required if config.responseAttributes is passed.
organization Organization	The organization tied to the service provider.

Optional
config.nameIdFormat string	The format for the name field. Possible values are : UNSPECIFIED, EMAIL_ADDRESS, X509_SUBJECT, WINDOWS_DQN, KERBEROS_PRINCIPAL, ENTITY, PERSISTENT and TRANSIENT. If not provided this defaults to UNSPECIFIED.
config.responseAttributes.nameFormat string	The format for the name field. Possible values are : UNSPECIFIED, URI and BASIC. If not provided this defaults to UNSPECIFIED.
config.responseAttributes Array[Object]	The list of attributes part of the response.

Delete service provider

DELETE /service_providers/:id

# Delete a service provider
curl "https://cloudmc_endpoint/api/v1/service_providers/:id" \
   -X DELETE -H "MC-Api-Key: your_api_key"

Delete a specific service provider

Get service provider metadata file

GET /service_providers/:id/metadata

# Get a service provider's metadata file
curl "https://cloudmc_endpoint/rest/service_providers/:id/metadata"

> The above command returns XML structured like this:

```xml
<md:EntityDescriptor entityID="https://cloudmc_endpoint">
    <ds:Signature>
        <ds:SignedInfo>
            <ds:CanonicalizationMethod Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
            <ds:SignatureMethod Algorithm="http://www.w3.org/2001/04/xmldsig-more#rsa-sha256"/>
            <ds:Reference URI="">
                <ds:Transforms>
                    <ds:Transform Algorithm="http://www.w3.org/2000/09/xmldsig#enveloped-signature"/>
                    <ds:Transform Algorithm="http://www.w3.org/2001/10/xml-exc-c14n#"/>
                </ds:Transforms>
                <ds:DigestMethod Algorithm="http://www.w3.org/2001/04/xmlenc#sha256"/>
                <ds:DigestValue>5U/iSjUM0ooVDT5n60sK1vgPchsZbVyp+Epm7P/GP8Y=</ds:DigestValue>
            </ds:Reference>
        </ds:SignedInfo>
        <ds:SignatureValue>
k2k3+9IbMkUCIN/TmcZMmrG3AB6izICW10bjtnjSocz+RgnAwrUEoNQTYsOG4nsEcHFZ31zxuRJq YOnjJ259XcPGsTrZSmV/GIWxYwUcPUP292D00Ulql+Gpj5YVk31uoaWQ93fln42hbwW6Qkaaiz9i +4OXASSxx8WgBpG4Ro0Carm0fT7nJU55+ZX0bFiKRCBmbUhxXivbVj914ed2vFjkWoucG1NXvIdF L+j3Qhn3DAd/XUvR06WfPWModAl7ip/+GH97QkE7sq4szcRAKzrR10kFVLFBbMu/zZ1a0FMSc1tC vZKh1SAA61IYZy/j9OuYGCELt59f2wd+5X1+7w==
</ds:SignatureValue>
        <ds:KeyInfo>
            <ds:X509Data>
                <ds:X509Certificate>CERT_DATA</ds:X509Data>
        </ds:KeyInfo>
    </ds:Signature>
    <md:IDPSSODescriptor WantAuthnRequestsSigned="true" protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect">
        <md:KeyDescriptor use="signing">
            <ds:KeyInfo>
                <ds:X509Data>
                    <ds:X509Certificate>CERT_DATA</ds:X509Data>
            </ds:KeyInfo>
        </md:KeyDescriptor>
        <md:NameIDFormat>
urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified
</md:NameIDFormat>
        <md:SingleSignOnService Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect" Location="https://cloudmc_endpoint/rest/service_providers/f9dea588-d7ab-4f42-b6e6-4b85f273f3db"/>
        <saml2:Attribute Name="first-name" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified"/>
    </md:IDPSSODescriptor>
</md:EntityDescriptor>

Gets the metadata file for a given service provider. This can be provided to certain identity providers for quick set-up.

SAML settings

Allows to change the configuration for the service provider integrated with SAML.

List SAML settings

GET /saml_settings?organization_id=:organization_id

# Retrieve SAML settings
curl "https://cloudmc_endpoint/api/v1/saml_settings?organization_id=:organization_id" \
   -H "MC-Api-Key: your_api_key"

Optional query parameters
organization_id string	The organization whose SAML settings are to be retrieved. If this is not provided then the request defaults to the user's organization.

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
      "certificate": "certificate value",
      "privateKey": "private key value",
      "organization": {
        "id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
      }
    }
  ]
}

List the SAML settings of an organization

Attributes
id UUID	The id of the SAML setting.
certificate string	The certificate sent in the SAML response for the service provider to validate the signature.
privateKey string	The private key used to sign the SAML request.
organization Organization	The organization tied to the SAML settings.

Retrieve SAML settings

GET /saml_settings/:id

# Retrieve saml settings
curl "https://cloudmc_endpoint/api/v1/saml_settings/:id" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
    "certificate": "certificate value",
    "privateKey": "private key value",
    "organization": {
      "id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
    }
  }
}

Return the SAML settings of an organization

Attributes
id UUID	The id of the SAML setting.
certificate string	The certificate sent in the SAML response for the service provider to validate the signature.
privateKey string	The private key used to sign the SAML request.
organization Organization	The organization tied to the SAML settings.

Create SAML settings

POST /saml_settings

# Updates an existing saml settings
curl -X POST "https://cloudmc_endpoint/api/v1/saml_settings/:id" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
    "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
    "certificate": "certificate value",
    "privateKey": "private key value",
    "organization": {
      "id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
    }
}

The above command return JSON structured like this:

{
  "data": {
    "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
    "certificate": "certificate value",
    "privateKey": "private key value",
    "organization": {
      "id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
    }
  }
}

Creates a specific SAML settings

Required
certificate string	The certificate sent in the SAML response for the service provider to validate the signature. It must use the SHA-256 algorithm.
privateKey string	The private key used to sign the SAML request. It must be an RSA key of 2048 bits.
organization Organization	The organization tied to the SAML settings.

Update SAML settings

PUT /saml_settings/:id

# Updates an existing saml settings
curl -X PUT "https://cloudmc_endpoint/api/v1/saml_settings/:id" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
    "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
    "certificate": "certificate value",
    "privateKey":  "private key value",
    "organization": {
      "id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
    }
}

The above command return JSON structured like this:

{
  "data": {
    "id": "04b77783-516f-4064-a6df-e7f9cae222c1",
    "certificate": "certificate value",
    "privateKey": "private key value",
    "organization": {
      "id": "a310f701-1d77-4bda-b3f7-8c514c5a005e"
    }
  }
}

Updates a specific SAML settings

Required
id UUID	The id of the SAML setting.
certificate string	The certificate sent in the SAML response for the service provider to validate the signature. It must use the SHA-256 algorithm.
privateKey string	The private key used to sign the SAML request. It must be an RSA key of 2048 bits.
organization Organization	The organization tied to the SAML settings.

Delete SAML settings

DELETE /saml_settings/:id

# Updates an existing saml settings
curl -X DELETE "https://cloudmc_endpoint/api/v1/saml_settings/:id" \
   -H "MC-Api-Key: your_api_key"

Deletes a specific SAML settings

Attributes
id UUID	The id of the SAML setting

Branding

Manage branding.

List brandings

GET /brandings

# Retrieve branding
curl "https://cloudmc_endpoint/rest/brandings" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "671f113c-dbbb-4478-be9c-90765b3259e5",
      "factory": false,
      "defaultLanguage": "en",
      "organization": {
        "id": "23910576-d29f-4c14-b663-31d728ff49a5"
      },
      "activeLanguages": "en,fr,es",
      "defaultTimezone": "America/Montreal",
      "applicationName": "CloudMC application",
      "artifacts": [
        {
          "createdAt": "2020-09-14T11:42:52.000Z",
          "name": "android-chrome-144x144.png",
          "id": "642c73cf-d675-4b6f-826b-72d1a240542e",
          "mimeType": "image/png",
          "type": "FAVICON",
          "content": "iVBOR...kJggg==",
          "updatedAt": "2020-09-14T11:42:52.000Z"
        }
      ]
    }
  ]
}

List the branding configured for the organization.

Query Params
organization_id UUID	Return only the branding for the provided organization id. If not provided, will default to the user's organization.

Attributes
id UUID	The id of the branding.
organization.id UUID	The organization id that the branding is linked to.
defaultLanguage string	The default language.
activeLanguages Array[string]	List of the possible languages.
defaultTimezone string	The default timezone.
applicationName string	The application name displayed to the user.
factory boolean	If the branding is the factory branding.
artifacts Array[Object]	The list of artifacts linked to the branding. This includes the custom css, colours css, logos, favicons.
artifacts.id UUID	The artifact id.
artifacts.name string	The artifact name.
artifacts.mimeType string	The mime type of the artifact.
artifacts.type string	The artifact type. The possibles values are: LOGO, LOGO_SQUARE, FAVICON, CUSTOM_CSS, COLORS.
artifacts.content string	The artifact content.
artifacts.createdAt string	The artifact creation date.
artifacts.updatedAt string	The artifact update date.

Retrieve branding

GET /brandings/:id

# Retrieve knowledge base
curl "https://cloudmc_endpoint/rest/brandings/671f113c-dbbb-4478-be9c-90765b3259e5" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "id": "671f113c-dbbb-4478-be9c-90765b3259e5",
    "factory": false,
    "defaultLanguage": "en",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "activeLanguages": "en,fr,es",
    "defaultTimezone": "America/Montreal",
    "applicationName": "CloudMC application",
    "artifacts": [
      {
        "createdAt": "2020-09-14T11:42:52.000Z",
        "name": "android-chrome-144x144.png",
        "id": "642c73cf-d675-4b6f-826b-72d1a240542e",
        "mimeType": "image/png",
        "type": "FAVICON",
        "content": "iVBOR...kJggg==",
        "updatedAt": "2020-09-14T11:42:52.000Z"
      }
    ]
  }
}

Retrieve the branding associated to the id.

Attributes
id UUID	The id of the branding.
organization.id UUID	The organization id that the branding is linked to.
defaultLanguage string	The default language.
activeLanguages Array[string]	List of the possible languages.
defaultTimezone string	The default timezone.
applicationName string	The application name displayed to the user.
factory boolean	If the branding is the factory branding.
artifacts Array[Object]	The list of artifacts linked to the branding. This includes the custom css, colours css, logos, favicons.
artifacts.id UUID	The artifact id.
artifacts.name string	The artifact name.
artifacts.mimeType string	The mime type of the artifact.
artifacts.type string	The artifact type. The possibles values are: LOGO, LOGO_SQUARE, FAVICON, CUSTOM_CSS, COLORS.
artifacts.content string	The artifact content.
artifacts.createdAt string	The artifact creation date.
artifacts.updatedAt string	The artifact update date.

Knowledge Base

Manage knowledge base.

List knowledge base

GET /content/kb

# Retrieve branding
curl "https://cloudmc_endpoint/rest/content/kb" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "organizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
      "sources": [
        {
          "createdDate": "2020-07-27T15:46:58Z",
          "lastSyncDate": "2020-09-24T15:54:32Z",
          "id": "585bd805-5b85-44af-9800-a9e55b2f619c",
          "branch": "master",
          "url": "https://github.com/cloudops/cloudmc-standard-kb"
        }
      ],
      "id": "1de30074-dac8-4c8b-8eda-585f9fad9c49",
      "state": "READY",
      "categories": [
        {
          "createdAt": "2020-07-27T15:46:59.000Z",
          "featured": false,
          "externalDocumentation": [
            {
              "language": "en",
              "url": "http://docs.cloudstack.apache.org/en/latest/"
            },
            {
              "language": "es",
              "url": "http://docs.cloudstack.apache.org/en/latest/"
            },
            {
              "language": "fr",
              "url": "http://docs.cloudstack.apache.org/en/latest/"
            }
          ],
          "translations": [
            {
              "language": "en",
              "id": "35b2b5e0-4944-4f92-9ddb-68eb980a31b2",
              "text": "CloudStack Service",
              "type": "title",
              "version": 1
            },
            {
              "language": "en",
              "id": "27cb1d2d-d624-4fe7-b0d1-8677c5f3200a",
              "text": "cloudstack-compute-service",
              "type": "url_slug",
              "version": 1
            }
          ],
          "icon": "fa fa-cloud",
          "rank": 2,
          "id": "47789e16-ef75-4cf8-82f7-747098533e63",
          "gitKey": "cloudstack-compute-service",
          "articles": [
            {
              "createdAt": "2020-07-27T15:47:01.000Z",
              "translations": [
                {
                  "language": "fr",
                  "id": "83297d87-e984-42b8-9356-2edef188b6c5",
                  "text": "Gestion des modèles",
                  "type": "title",
                  "version": 1
                },
                {
                  "language": "fr",
                  "id": "07bec89a-870e-4506-9d45-8ea977b2f9f2",
                  "text": "gestion-des-modeles",
                  "type": "url_slug",
                  "version": 1
                },
                {
                  "language": "fr",
                  "id": "aa2deeee-39a6-40f8-886b-1779c8bdbfa0",
                  "text": "\n\n### Créer un modèle à partir d'une instance existante...",
                  "type": "body",
                  "version": 2
                }
              ],
              "rank": 9,
              "id": "05353b4b-5675-4631-b91a-6872f385c3b5",
              "published": true,
              "gitKey": "cloudstack-compute-service/working-with-instance-templates",
              "updatedAt": "2020-09-24T15:54:36.000Z"
            }
          ],
          "updatedAt": "2020-09-24T15:54:34.000Z"
        }
      ]
    }
  ]
}

List the knowledge base configured for the organization.

Query Params
organization_id UUID	Return only the knowledge base for the provided organization id. If not provided, will default to the user's organization.

Attributes
id UUID	The id of the knowledge base.
organization.id UUID	The organization id that the knowledge base is linked to.
state string	The source state. Possible values: IMPORTING, SYNCHING, READY, ERROR.
sources Array[Object]	List of sources associated to the knowledge base
sources.id UUID	The source id.
sources.url string	The source URL.
sources.branch string	The source branch.
sources.createdDate string	The date the source was created.
sources.lastSyncDate string	The last date the source was synchronized.
categories.id UUID	The category id.
categories.gitKey string	The category git key.
categories.rank integer	The category rank.
categories.icon string	The category icon.
categories.createdAt string	The creation date.
categories.updatedAt string	The update date.
categories.featured boolean	If the category needs to be displayed.
categories.externalDocumentation Array[Object]	List of URL and language objects. Only either 1) articles, or, 2) external documentation, will be provided for a category (example above shows both only as an example for the object structure).
categories.externalDocumentation.language string	Language of the external documentation. This indicates which URL to use based on the help center selected language.
categories.externalDocumentation.url string	URL link to the external documentation.
categories.translations Array[Object]	The translation objects for the category.
categories.translations.id UUID	The id of the translation.
categories.translations.language string	The language of the translation.
categories.translations.text string	The content of the translation.
categories.translations.type string	The type of translation. Possible values are: title or url_slug.
categories.translations.version integer	The version of the translation.
categories.articles Array[Object]	The list of articles in the category.
categories.articles.id UUID	The id of the article.
categories.articles.published boolean	If the article is published.
categories.articles.rank integer	The article rank.
categories.articles.gitKey string	The article git key.
categories.articles.createdAt string	The creation date.
categories.articles.updatedAt string	The update date.
categories.articles.translations Array[Object]	The translation objects for the article.
categories.articles.translations.id UUID	The id of the translation.
categories.articles.translations.language string	The language of the translation.
categories.articles.translations.text string	The content of the translation.
categories.articles.translations.type string	The type of translation. Possible values are: title, body or url_slug.
categories.articles.translations.version integer	The version of the translation.

Retrieve knowledge base

GET /content/kb/:id

# Retrieve trial settings
curl "https://cloudmc_endpoint/rest/content/kb/671f113c-dbbb-4478-be9c-90765b3259e5" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "organizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
    "sources": [
      {
        "createdDate": "2020-07-27T15:46:58Z",
        "lastSyncDate": "2020-09-24T15:54:32Z",
        "id": "585bd805-5b85-44af-9800-a9e55b2f619c",
        "branch": "master",
        "url": "https://github.com/cloudops/cloudmc-standard-kb"
      }
    ],
    "id": "1de30074-dac8-4c8b-8eda-585f9fad9c49",
    "state": "READY",
    "categories": [
      {
        "createdAt": "2020-07-27T15:46:59.000Z",
        "featured": false,
        "externalDocumentation": [
            {
              "language": "en",
              "url": "http://docs.cloudstack.apache.org/en/latest/"
            },
            {
              "language": "es",
              "url": "http://docs.cloudstack.apache.org/en/latest/"
            },
            {
              "language": "fr",
              "url": "http://docs.cloudstack.apache.org/en/latest/"
            }
          ],
        "translations": [
          {
           "language": "en",
           "id": "35b2b5e0-4944-4f92-9ddb-68eb980a31b2",
           "text": "CloudStack Service",
           "type": "title",
           "version": 1
          },
          {
            "language": "en",
            "id": "27cb1d2d-d624-4fe7-b0d1-8677c5f3200a",
            "text": "cloudstack-compute-service",
            "type": "url_slug",
            "version": 1
          }
        ],
        "icon": "fa fa-cloud",
        "rank": 2,
        "id": "47789e16-ef75-4cf8-82f7-747098533e63",
        "gitKey": "cloudstack-compute-service",
        "articles": [
          {
            "createdAt": "2020-07-27T15:47:01.000Z",
            "translations": [
              {
                "language": "fr",
                "id": "83297d87-e984-42b8-9356-2edef188b6c5",
                "text": "Gestion des modèles",
                "type": "title",
                "version": 1
              },
              {
                "language": "fr",
                "id": "07bec89a-870e-4506-9d45-8ea977b2f9f2",
                "text": "gestion-des-modeles",
                "type": "url_slug",
                "version": 1
              },
              {
                "language": "fr",
                "id": "aa2deeee-39a6-40f8-886b-1779c8bdbfa0",
                "text": "\n\n### Créer un modèle à partir d'une instance existante...",
                "type": "body",
                "version": 2
              }
            ],
            "rank": 9,
            "id": "05353b4b-5675-4631-b91a-6872f385c3b5",
            "published": true,
            "gitKey": "cloudstack-compute-service/working-with-instance-templates",
            "updatedAt": "2020-09-24T15:54:36.000Z"
          }
        ],
        "updatedAt": "2020-09-24T15:54:34.000Z"
      }
    ]
  }
}

Retrieve the branding associated to the id.

Attributes
id UUID	The id of the knowledge base.
organization.id UUID	The organization id that the knowledge base is linked to.
state string	The source state. Possible values: IMPORTING, SYNCHING, READY, ERROR.
sources Array[Object]	List of sources associated to the knowledge base
sources.id UUID	The source id.
sources.url string	The source URL.
sources.branch string	The source branch.
sources.createdDate string	The date the source was created.
sources.lastSyncDate string	The last date the source was synchronized.
categories.id UUID	The category id.
categories.gitKey string	The category git key.
categories.rank integer	The category rank.
categories.icon string	The category icon.
categories.createdAt string	The creation date.
categories.updatedAt string	The update date.
categories.featured boolean	If the category needs to be displayed.
categories.externalDocumentation Array[Object]	List of URL and language objects. Only either 1) articles, or, 2) external documentation, will be provided for a category (example above shows both only as an example for the object structure).
categories.externalDocumentation.language string	Language of the external documentation. This indicates which URL to use based on the help center selected language.
categories.externalDocumentation.url string	URL link to the external documentation.
categories.translations Array[Object]	The translation objects for the category.
categories.translations.id UUID	The id of the translation.
categories.translations.language string	The language of the translation.
categories.translations.text string	The content of the translation.
categories.translations.type string	The type of translation. Possible values are: title or url_slug.
categories.translations.version integer	The version of the translation.
categories.articles Array[Object]	The list of articles in the category.
categories.articles.id UUID	The id of the article.
categories.articles.published boolean	If the article is published.
categories.articles.rank integer	The article rank.
categories.articles.gitKey string	The article git key.
categories.articles.createdAt string	The creation date.
categories.articles.updatedAt string	The update date.
categories.articles.translations Array[Object]	The translation objects for the article.
categories.articles.translations.id UUID	The id of the translation.
categories.articles.translations.language string	The language of the translation.
categories.articles.translations.text string	The content of the translation.
categories.articles.translations.type string	The type of translation. Possible values are: title, body or url_slug.
categories.articles.translations.version integer	The version of the translation.

Trials

Manage trials and trials settings.

Trials Settings

Manage trials settings.

List trials settings

GET /trials_settings

# Retrieve trials settings
curl "https://cloudmc_endpoint/rest/trials_settings" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
      "organization": {
        "id": "23910576-d29f-4c14-b663-31d728ff49a5",     
      },
      "duration": 14,
      "extensionDays": 7,
      "maxConcurrentTrials": 5,
      "cleanupDelayDays": 5,
      "expirationReminderDays": 3,
      "allowMultipleTrialSameEmail": false,
      "enableRecaptcha": true,
      "recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
      "recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
      "contactUsEmail": "email@gmail.com",
      "contactUsPhone": "555-555-555",
      "registrationHTML": {
        "en": "<div>Registration HTML EN</div>",
        "fr": "<div>Registration HTML FR</div>"
      },
      "termsAndConditionsHTML": {
        "en": "<div>Terms and conditions HTML EN</div>",
        "fr": "<div>Terms and conditions HTML FR</div>"
      }
    }
  ]
}

List the trials settings configured on the system.

Query Params
organization_id UUID	Return only settings for the provided organization id. If not provided, will default to the user organization.

Attributes
id UUID	The id of the trial settings.
organization.id UUID	The organization id that the trial settings is linked to.
duration integer	The number of days a trial account will remain active.
extensionDays integer	The number of days that a trial administrator adds when extending an active trial.
maxConcurrentTrials integer	The number of organizations that can concurrently have an active trial account. A value of zero indicates that there is no upper limit.
cleanupDelayDays integer	The number of days after the trial expiration before the system will delete the trial's resources.
expirationReminderDays integer	The number of days before the trial's end that the trial administrator will receive an email notification that the trial is about to expire.
allowMultipleTrialSameEmail boolean	If more than one trial account can be created using the same email address.
enableRecaptcha boolean	If the reCAPTCHA verification on the sign up form is displayed. The reCAPTCHA site key and secret key must be present.
recaptchaSitekey string	The site key obtained from the reCAPTCHA admin console (Google).
recaptchaSecretkey string	The secret key obtained from the reCAPTCHA admin console (Google).
contactUsEmail string	The email address that trial user can contact for more info/support.
contactUsPhone string	The phone number that trial user can contact for more info/support.
registrationHTML Object	Mapped object containing the registration information HTML in different languages.
termsAndConditionsHTML Object	Mapped object containing the terms and conditions HTML name in different languages.

Retrieve trial settings

GET /trials_settings/:id

# Retrieve trial settings
curl "https://cloudmc_endpoint/rest/trials_settings/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5",     
    },
    "duration": 14,
    "extensionDays": 7,
    "maxConcurrentTrials": 5,
    "cleanupDelayDays": 5,
    "expirationReminderDays": 3,
    "allowMultipleTrialSameEmail": false,
    "enableRecaptcha": true,
    "recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
    "recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
    "contactUsEmail": "email@gmail.com",
    "contactUsPhone": "555-555-555",
    "registrationHTML": {
      "en": "<div>Registration HTML EN</div>",
      "fr": "<div>Registration HTML FR</div>"
    },
    "termsAndConditionsHTML": {
      "en": "<div>Terms and conditions HTML EN</div>",
      "fr": "<div>Terms and conditions HTML FR</div>"
    }
  }
}

Retrieve the trial settings configured associated to the id on the system.

Attributes
id UUID	The id of the trial settings.
organization.id UUID	The organization id that the trial settings is linked to.
duration integer	The number of days a trial account will remain active.
extensionDays integer	The number of days that a trial administrator adds when extending an active trial.
maxConcurrentTrials integer	The number of organizations that can concurrently have an active trial account. A value of zero indicates that there is no upper limit.
cleanupDelayDays integer	The number of days after the trial expiration before the system will delete the trial's resources.
expirationReminderDays integer	The number of days before the trial's end that the trial administrator will receive an email notification that the trial is about to expire.
allowMultipleTrialSameEmail boolean	If more than one trial account can be created using the same email address.
enableRecaptcha boolean	If the reCAPTCHA verification on the sign up form is displayed. The reCAPTCHA site key and secret key must be present.
recaptchaSitekey string	The site key obtained from the reCAPTCHA admin console (Google).
recaptchaSecretkey string	The secret key obtained from the reCAPTCHA admin console (Google).
contactUsEmail string	The email address that trial user can contact for more info/support.
contactUsPhone string	The phone number that trial user can contact for more info/support.
registrationHTML Object	Mapped object containing the registration information HTML in different languages.
termsAndConditionsHTML Object	Mapped object containing the terms and conditions HTML name in different languages.

Update trial settings

PUT /trials_settings/:id

# Updates an existing trial's settings
curl -X PUT "https://cloudmc_endpoint/rest/trials_settings/:id" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
  "organization": {
    "id": "23910576-d29f-4c14-b663-31d728ff49a5",     
  },
  "organizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
  "duration": 14,
  "extensionDays": 7,
  "maxConcurrentTrials": 5,
  "cleanupDelayDays": 5,
  "expirationReminderDays": 3,
  "allowMultipleTrialSameEmail": false,
  "enableRecaptcha": true,
  "recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
  "recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
  "contactUsEmail": "email@gmail.com",
  "contactUsPhone": "555-555-555",
  "registrationHTML": {
    "en": "<div>Registration HTML EN</div>",
    "fr": "<div>Registration HTML FR</div>"
  },
  "termsAndConditionsHTML": {
    "en": "<div>Terms and conditions HTML EN</div>",
    "fr": "<div>Terms and conditions HTML FR</div>"
  }
}

The above command return JSON structured like this:

{
  "data": {
    "id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5",     
    },
    "duration": 14,
    "extensionDays": 7,
    "maxConcurrentTrials": 5,
    "cleanupDelayDays": 5,
    "expirationReminderDays": 3,
    "allowMultipleTrialSameEmail": false,
    "enableRecaptcha": true,
    "recaptchaSitekey": "6Lfg9rkZAAAAAHAwlr6_qs4QBTFRHVFgLhK3XXX",
    "recaptchaSecretkey": "6Lfg9rkZAAAAAOSjYqghXeQ7zfagZTqXXXRmXXE",
    "contactUsEmail": "email@gmail.com",
    "contactUsPhone": "555-555-555",
    "registrationHTML": {
      "en": "<div>Registration HTML EN</div>",
      "fr": "<div>Registration HTML FR</div>"
    },
    "termsAndConditionsHTML": {
      "en": "<div>Terms and conditions HTML EN</div>",
      "fr": "<div>Terms and conditions HTML FR</div>"
    }
  }
}

Updates a specific trial's settings.

Required
id UUID	The id of the trial settings.
organization.id UUID	The organization id that the trial settings is linked to. It cannot be changed.
duration integer	The number of days a trial account will remain active.
extensionDays integer	The number of days that a trial administrator adds when extending an active trial.
maxConcurrentTrials integer	The number of organizations that can concurrently have an active trial account. A value of zero indicates that there is no upper limit.
cleanupDelayDays integer	The number of days after the trial expiration before the system will delete the trial's resources.
expirationReminderDays integer	The number of days before the trial's end that the trial administrator will receive an email notification that the trial is about to expire.
allowMultipleTrialSameEmail boolean	If more than one trial account can be created using the same email address.
contactUsEmail string	The email address that trial user can contact for more info/support.
registrationHTML Object	Mapped object containing the registration information HTML in different languages.
termsAndConditionsHTML Object	Mapped object containing the terms and conditions HTML name in different languages.

Optional
contactUsPhone string	The phone number that trial user can contact for more info/support.
enableRecaptcha boolean	If the reCAPTCHA verification on the sign up form is displayed. The reCAPTCHA site key and secret key must be present. Default is false.
recaptchaSitekey string	The site key obtained from the reCAPTCHA admin console (Google). Mandatory if recaptcha is enabled.
recaptchaSecretkey string	The secret key obtained from the reCAPTCHA admin console (Google). Mandatory if recaptcha is enabled.

Trials Management

Manage trials through it lifecycle.

List trials

GET /trials

# Retrieve trials
curl "https://cloudmc_endpoint/rest/trials" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "expiryDate": "2020-10-24T13:38:57.000Z",
      "hasActivatedUser": false,
      "firstName": "John",
      "lastName": "Doe",
      "persistedOrganizationId": "0518842d-1ad6-4b66-abc4-2cf48d502b4c",
      "resellerOrganization": {
        "id": "23910576-d29f-4c14-b663-31d728ff49a5",     
      },
      "createdDate": "2020-10-19T13:36:25.000Z",
      "organizationName": "John Doe Corp",
      "activity": [
        5,
        1,
        0,
        null,
        null,
        null
      ],
      "organization": {
        "serviceConnections": [
          {
            "commitmentTrackingEnabled": false,
            "metricsTrackingEnabled": false,
            "serviceCode": "gcp",
            "iconOverrideUrl": "",
            "name": "gcp",
            "locations": [],
            "id": "749e314b-d979-4882-9ba8-417862381266",
            "state": "PROVISIONED",
            "type": "gcp",
            "reachable": true,
            "trialEnvironmentLimit": 2
          }
        ],
        "name": "John Doe Corp",
        "id": "0518842d-1ad6-4b66-abc4-2cf48d502b4c"
      },
      "id": "019d31ed-fae2-4c83-96e6-1e67c5ac5192",
      "email": "john.doe@yahoo.com",
      "status": "ONGOING"
    }
  ]
}

List the trials configured on the system.

Query Params
organization_id UUID	Return only settings for the provided organization id. If not provided, will default to the user organization.

Attributes
id UUID	The id of the trial.
resellerOrganization.id UUID	The reseller organization id that the trial belongs to.
status string	The status of the trial. Possible values are: SUBMITTED, PENDING, DENIED, ONGOING, EXPIRED, PURGED, CONVERTED.
firstName string	The first name of the person that requested the trial.
lastName string	The last name of the person that requested the trial.
email string	The email address of the person that requested the trial.
organizationName string	The name of the organization for which the requester is doing the trial for.
createdDate string	The creation date of the trial.
expiryDate string	The expiration date of the trial.
persistedOrganizationId UUID	The id of the organization created in the system once the trial is approved.
organization Object	The organization object created in the system for this organization once the trial is approved.

Retrieve trial

GET /trials/:id

# Retrieve trial
curl "https://cloudmc_endpoint/rest/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "id": "b41f2aa3-e2d1-48d8-9760-8b874c20e8ae",
    "resellerOrganization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5",     
    },
    "lastName": "Doe",
    "approvalDate": "2020-10-19T13:38:57.000Z",
    "activity": [
      5,
      1,
      0,
      null,
      null,
      null
    ],
    "extensionEmailDate": "2020-10-21T14:09:18.000Z",
    "language": "en",
    "blurb": "We need CloudMC services",
    "expiryDate": "2020-10-24T13:38:57.000Z",
    "email": "john.doe@yahoo.com",
    "organizationName": "John Doe Corp",
    "manuallyApproved": false,
    "extensionCount": 0,
    "hasActivatedUser": false,
    "firstName": "John",
    "persistedOrganizationId": "0518842d-1ad6-4b66-abc4-2cf48d502b4c",
    "createdDate": "2020-10-19T13:36:25.000Z",
    "phoneNumber": "5144436363",
    "organization": {
      "serviceConnections": [
        {
          "commitmentTrackingEnabled": false,
          "metricsTrackingEnabled": false,
          "serviceCode": "gcp",
          "iconOverrideUrl": "",
          "name": "gcp",
          "locations": [],
          "id": "749e314b-d979-4882-9ba8-417862381266",
          "state": "PROVISIONED",
          "type": "gcp",
          "reachable": true,
          "trialEnvironmentLimit": 2
        }
      ],
      "name": "John Doe Corp",
      "id": "0518842d-1ad6-4b66-abc4-2cf48d502b4c"
    },
    "username": "john.doe@yahoo.com",
    "status": "ONGOING"
  }
}

Retrieve the trial associated to the id on the system.

Attributes
id UUID	The id of the trial.
resellerOrganization.id UUID	The reseller organization id that the trial belongs to.
status string	The status of the trial. Possible values are: SUBMITTED, PENDING, DENIED, ONGOING, EXPIRED, PURGED, CONVERTED.
firstName string	The first name of the person that requested the trial.
lastName string	The last name of the person that requested the trial.
email string	The email address of the person that requested the trial.
phoneNumber string	The phone number of the person that requested the trial.
organizationName string	The name of the organization for which the requester is doing the trial for.
createdDate string	The creation date of the trial.
expiryDate string	The expiration date of the trial.
persistedOrganizationId UUID	The id of the organization created in the system once the trial is approved.
organization Object	The organization object created in the system for this organization once the trial is approved.
username string	The username associated to the creator of the trial.
approvalDate string	The approval date of the trial.
denialDate string	The denial date of the trial.
denialReason string	The reason the trial is denied.
extensionCount integer	The number of times the trial was extended.
language string	The language used when creating the trial.
manuallyApproved boolean	If the trial is manually approved.
extensionEmailDate string	The date the extension email notification was sent.
extensionDate string	The date the trial was extended.
shutdownDate string	The date the trial was shutdown.
purgeDate string	The date the trial was purged.
conversionDate string	The date the trial was converted to an active organization.
blurb string	The cloud requirements entered in the trial registration.

Trial remaining slots

POST /trials/:id/remaining

# Get trial remaining slots
curl -X GET "https://cloudmc_endpoint/rest/trials/remaining" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": 10
}

Indicates how many organizations can concurrently have an active trial with automatic approval.

Query Params
organization_id UUID	Return only settings for the provided organization id. If not provided, it will default to the reseller configuration matching the url.

Activate trial

POST /trials/:id/activate

# Activate a trial
curl -X PUT "https://cloudmc_endpoint/rest/trials/:id/activate" \
   -H "MC-Api-Key: your_api_key"

Activate the trial for the provided id.

Extend trial

POST /trials/:id/extend

# Extend a trial
curl -X PUT "https://cloudmc_endpoint/rest/trials/:id/extend" \
   -H "MC-Api-Key: your_api_key"

Extend the trial for the provided id.

Query Params
extendDate long	The date in a long format to which the trial will be extend to. Default value is the expired date adding with the number of days for an extension defined in the trial settings.

Terminal trial

POST /trials/:id/terminate

# Extend a trial
curl -X PUT "https://cloudmc_endpoint/rest/trials/:id/terminate" \
   -H "MC-Api-Key: your_api_key"

Terminate the trial for the provided id.

Query Params
purge boolean	Indicate if the trial needs to be purge as well. Default is false.

Deny trial

POST /trials/:id/deny

# Deny a trial
curl -X PUT "https://cloudmc_endpoint/rest/trials/:id/deny" \
   -H "MC-Api-Key: your_api_key"

Request body example:

As per client request

Deny the trial for the provided id. The body of the request is the reason for being denied.

Convert to billable

POST /trials/:id/convertToBillable

# Cnvert to billable a trial
curl -X PUT "https://cloudmc_endpoint/rest/trials/:id/convertToBillable" \
   -H "MC-Api-Key: your_api_key"

Convert to billable the trial for the provided id.

Query Params
billableStartDate long	The date time in a long format for which the trial will be converted. It is mandatory.

Retrieve trial activities

GET /trials/:id/activity

# Retrieve trial activities
curl "https://cloudmc_endpoint/rest/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae/activity" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "userLastname": "Doe",
      "organizationId": "0518842d-1ad6-4b66-abc4-2cf48d502b4c",
      "requesterIp": "127.0.0.1",
      "userEmail": "john.doe@yahoo.com",
      "id": "5e854a75-11d2-47ea-a1b4-df7d5886294c",
      "userOrganizationId": "23910576-d29f-4c14-b663-31d728ff49a5",
      "organizationName": "John Doe corpo",
      "created": "2020-10-20T15:41:18.666Z",
      "userId": "39f2b0ea-85f0-49a0-b005-c34fa62baf27",
      "eventContext": "{...}",
      "eventCode": "email_template.preview",
      "userFirstname": "John",
      "userOrganizationName": "System",
      "category": "SYSTEM",
      "updated": "2020-10-20T15:41:19.149Z",
      "status": "SUCCESS",
      "username": "john.doe@yahoo.com"
    }
  ]
}

Retrieve the activities related to the trial associated to the id on the system.

Attributes
id UUID	The activity Id.
organizationId UUID	The id of the organization impacted by the activity.
organizationName UUID	The name of the organization impacted by the activity.
userId UUID	The id of the person that made the activity.
username string	The username of the person that made the activity.
userOrganizationId UUID	The organization id of the user that made the activity.
userOrganizationName string	The organization name of the user that made the activity.
userFirstName string	The last name of the person that made the activity.
userLastName string	The last name of the person that made the activity.
userEmail string	The email address of the person that made the activity.
createdDate string	The creation date of the activity.
updatedDate string	The update date of the activity.
requesterIp string	The requester ip address
parentId UUID	The organization object created in the system for this organization once the trial is approved.
environmentId UUID	The id of the impacted environment.
environmentName string	The name of the impacted environment.
serviceConnectionId UUID	The id of the impacted service connection.
serviceConnectionName string	The name of the impacted service connection.
serviceConnectionType string	The type of the impacted service connection.
category string	The category of the activity. Possible values: SYSTEM, SERVICE_OPERATION.
status string	The status of the activity. Possible values: PENDING, SUCCESS, FAILURE, PARTIAL_SUCCESS.
eventContext string	Information link to the context of the activity in a JSON format.
serviceError string	Description of an error in the service operation activities.
apiKeyId UUID	The ID of the api key used to make this activity.
apiKeyName string	The name of the api key used to make this activity.

Retrieve trial users

GET /trials/:id/users

# Retrieve trial users
curl "https://cloudmc_endpoint/rest/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae/users" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "firstName": "John",
      "lastName": "Doe",
      "failedLoginCount": 0,
      "id": "11391f05-3828-49d7-b7f8-eca7f353cbc2",
      "userName": "john.doe@yahoo.com",
      "loginCount": 0
    }
  ]
}

Retrieve the users related to the trial associated to the id on the system.

Attributes
id UUID	The id of the trial.
firstName string	The first name of the user.
lastName string	The last name of the user.
username string	The username of the user.
failedLoginCount integer	The count of failed login for that user.
loginCount integer	The count of successful login for that user.
failedLoginCount integer	The count of failed login for that user.
lastLogin string	The date of the last login
lastFailedLogin string	The date of the last failed login

Resend trial email

GET /trials/:id/resend_email

# Resend trial email
curl "https://cloudmc_endpoint/rest/trials/b41f2aa3-e2d1-48d8-9760-8b874c20e8ae/resend_email" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": true
}

Resend a trial email based on the status and type provided. If no email is send, it returns false.

Query Param
email UUID	The type of email to resend. Possible values: validation, user_activation.

Retrieve trial statuses

GET /trials/statuses

# Retrieve trial statuses
curl "https://cloudmc_endpoint/rest/trials/statuses" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    "SUBMITTED",
    "PENDING",
    "DENIED",
    "ONGOING",
    "EXPIRED",
    "PURGED",
    "CONVERTED"
  ]
}

Retrieve the possible trial statuses in the application.

Email Settings

List email settings

GET /email_settings

# Retrieve email settings
curl "https://cloudmc_endpoint/rest/email_settings" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "mailgunPrivateKey": "VALIDPRIVATEKEY",
      "smtpHost": "valid.host",
      "smtpFromAddress": "valid.address@domain.com",
      "smtpUsername": "valid.username@gmail.com",
      "organization": {
          "id": "fb1b2caf-4ca4-4c45-b094-faa84bdabc47"
      },
      "smtpPort": 2,
      "mailgunDomain": "valid.mailgun.domain",
      "smtpPassword": "coolPassword",
      "smtpUseSsl": false,
      "id": "dc30f9a6-1edc-11eb-92b6-0242ac120003"
    }
  ]
}

List the email settings configured for the organization.

Query Params
organization_id UUID	Return only the settings for the provided organization id. If not provided, will default to the user's organization.

Attributes
id UUID	The configured email settings' id.
organization.id UUID	The organization id that the email settings are linked to.
smtpHost string	Hostname or IP address of your SMTP mail server (e.g. smtp.yourcompany.com).
smtpFromAddress string	Email address used in the 'sender address' (or 'from') field.
smtpUsername string	If your SMTP host requires authentication, specify the username of these authentication credentials here.
smtpPassword string	If your SMTP host requires authentication, specify the password associated with the username you specified.
smtpPort integer	SMTP port number, usually 25 for SMTP or 465 for SMTPS.
smtpUseSsl boolean	Set to true if your SMTP host uses the SSL protocol.
mailgunDomain string*	Domain name for the MailGun service.
mailgunPrivateKey string	Private key for the MailGun service.

Retrieve email settings

GET /email_settings/:id

# Retrieve knowledge base
curl "https://cloudmc_endpoint/rest/email_settings/dc30f9a6-1edc-11eb-92b6-0242ac120003" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "mailgunPrivateKey": "VALIDPRIVATEKEY",
    "smtpHost": "valid.host",
    "smtpFromAddress": "valid.address@domain.com",
    "smtpUsername": "valid.username@gmail.com",
    "organization": {
      "id": "fb1b2caf-4ca4-4c45-b094-faa84bdabc47"
    },
    "smtpPort": 2,
    "mailgunDomain": "valid.mailgun.domain",
    "smtpPassword": "coolPassword",
    "smtpUseSsl": false,
    "id": "dc30f9a6-1edc-11eb-92b6-0242ac120003"
  }
}

Retrieve the email settings associated to the email settings id.

Attributes
id UUID	The configured email settings' id.
organization.id UUID	The organization id that the email settings are linked to.
smtpHost string	Hostname or IP address of your SMTP mail server (e.g. smtp.yourcompany.com).
smtpFromAddress string	Email address used in the 'sender address' (or 'from') field.
smtpUsername string	If your SMTP host requires authentication, specify the username of these authentication credentials here.
smtpPassword string	If your SMTP host requires authentication, specify the password associated with the username you specified.
smtpPort integer	SMTP port number, usually 25 for SMTP or 465 for SMTPS.
smtpUseSsl boolean	Set to true if your SMTP host uses the SSL protocol.
mailgunDomain string*	Domain name for the MailGun service.
mailgunPrivateKey string	Private key for the MailGun service.

Update email settings

PUT /email_settings/:id

# Updates an existing email settings for an organization
curl -X PUT "https://cloudmc_endpoint/rest/email_settings/dc30f8f7-1edc-11eb-92b6-0242ac120003 \
   -H "MC-Api-Key: your_api_key"
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
  "organization": {
    "id": "ce77d759-c015-4a92-b594-3f7119867e1f"
  },
  "mailgunPrivateKey": "VALIDPRIVATEKEY",
  "smtpHost": "valid.host",
  "smtpFromAddress": "valid.address@domain.com",
  "smtpUsername": "valid.username@gmail.com",
  "smtpPort": 2,
  "mailgunDomain": "valid.mailgun.domain",
  "smtpPassword": "coolPassword",
  "smtpUseSsl": false,
  "id": "dc30f8f7-1edc-11eb-92b6-0242ac120003"
}

The above command return JSON structured like this:

{
  "data": {
    "mailgunPrivateKey": "VALIDPRIVATEKEY",
    "smtpHost": "valid.host",
    "smtpFromAddress": "valid.address@domain.com",
    "smtpUsername": "valid.username@gmail.com",
    "organization": {
      "id": "ce77d759-c015-4a92-b594-3f7119867e1f"
    },
    "smtpPort": 2,
    "mailgunDomain": "valid.mailgun.domain",
    "smtpPassword": "coolPassword",
    "smtpUseSsl": false,
    "id": "dc30f8f7-1edc-11eb-92b6-0242ac120003"
  }
}

Updates the email settings of an organization.

Required
id UUID	The configured email settings' id.
organization.id UUID	The organization id that the email settings are linked to. It cannot be changed.

Optional
smtpHost string	Hostname or IP address of your SMTP mail server (e.g. smtp.yourcompany.com).
smtpFromAddress string	Email address used in the 'sender address' (or 'from') field.
smtpUsername string	If your SMTP host requires authentication, specify the username of these authentication credentials here.
smtpPassword string	If your SMTP host requires authentication, specify the password associated with the username you specified.
smtpPort integer	SMTP port number, usually 25 for SMTP or 465 for SMTPS.
smtpUseSsl boolean	Set to true if your SMTP host uses the SSL protocol.
mailgunDomain string*	Domain name for the MailGun service.
mailgunPrivateKey string	Private key for the MailGun service.

Feedback Settings

Find feedback settings associated to an organization

GET /feedback/find?organizationId=:id

Retrieve the feedback settings associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.

# Retrieve the feedback settings
curl "https://cloudmc_endpoint/api/v1/feedback/find?organizationId=fcda8d5a-0276-4de3-908f-b3bd0aff2491" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "widgetZesettings": "",
    "supportEmail": "support@company.com",
    "zendeskWidgetKey": "",
    "organization": {
      "id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
    },
    "feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
    "id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
    "matomoWebsiteId": "1",
    "version": 1,
    "feedbackEmail": "feedback@company.com"
  }
}

Retrieve feedback settings

GET /feedback/:id

Retrieve the feedback settings associated to a feedback setting id.

# Retrieve feedback settings
curl "https://cloudmc_endpoint/api/v1/feedback/f4be2785-ec67-474c-af3a-38ffecfa4094" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "widgetZesettings": "",
    "supportEmail": "support@company.com",
    "zendeskWidgetKey": "",
    "organization": {
      "id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
    },
    "feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
    "id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
    "matomoWebsiteId": "1",
    "version": 1,
    "feedbackEmail": "feedback@company.com"
  }
}

Retrieve the feedback settings associated to the feedback settings id.

Attributes
id UUID	The configured feedback settings' id.
organization.id UUID	The organization id that the feedback settings are linked to. It cannot be changed.
supportEmail string	Email address used for support requests.
feedbackEmail string	Email address used for feedback.
feedbackSlackWebhookUrl string	The slack webhook url used for feedback. Please refer to https://api.slack.com/messaging/webhooks.
zendeskWidgetKey string	The key taken from the Zendesk admin page. Only one of supportEmail and zendeskWidgetKey can be set.
widgetZesettings string	Content of the zeSettings as a JSON for customization. Please refer to https://developer.zendesk.com/embeddables/docs/widget/settings.
matomoHost string	The Matomo analytics subdomain, ending in '.matomo.cloud'.
matomoWebsiteId string	The website ID which Matomo's Javascript pushes events to.
version integer	The feedback settings version.

Create feedback

POST /feedback

Create a new feedback settings. The support can either be through email or a Zendesk widget, but not both.

# Creates a new feedback settings
curl -X POST "https://cloudmc_endpoint/api/v1/feedback" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
    "id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
    "organization": {
        "id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
    },
    "feedbackEmail": "feedback@company.com",
    "feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  "supportEmail": "",
  "widgetZesettings": "{ \"webWidget\": { \"color\": { \"theme\": \"#78a300\" } } }",
  "zendeskWidgetKey": "YourZendeskWidgetKey",
  "matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
  "matomoWebsiteId": "1",
}

The above command return JSON structured like this:

{
  "data": {
    "widgetZesettings": "{ \"webWidget\": { \"color\": { \"theme\": \"#78a300\" } } }",
    "supportEmail": "",
    "zendeskWidgetKey": "YourZendeskWidgetKey",
    "organization": {
      "id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
    },
    "feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
    "id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
    "matomoWebsiteId": "1",
    "version": 1,
    "feedbackEmail": "feedback@company.com"
  }
}

Required
id UUID	The configured feedback settings' id.
organization.id UUID	The organization id that the feedback settings are linked to. It cannot be changed.

Optional
supportEmail string	Email address used for support requests.
feedbackEmail string	Email address used for feedback.
feedbackSlackWebhookUrl string	The slack webhook url used for feedback. Please refer to https://api.slack.com/messaging/webhooks.
version integer	The feedback settings version.
zendeskWidgetKey string	The key taken from the Zendesk admin page. Only one of supportEmail and zendeskWidgetKey can be set.
widgetZesettings string	Content of the zeSettings as a JSON for customization. Please refer to https://developer.zendesk.com/embeddables/docs/widget/settings.
matomoHost string	The Matomo analytics subdomain, ending in '.matomo.cloud'. If specified, both the host and website ID are required.
matomoWebsiteId string	The website ID which Matomo's Javascript pushes events to. If specified, both the host and website ID are required.

Update feedback settings

PUT /feedback/:id

Updates the feedback settings of an organization. The support can either be through email or a Zendesk widget, but not both.

# Updates an existing feedback settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/v1/feedback/f4be2785-ec67-474c-af3a-38ffecfa4094 \
   -H "MC-Api-Key: your_api_key"
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
    "id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
    "organization": {
        "id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
    },
    "feedbackEmail": "feedback@company.com",
    "feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
  "supportEmail": "support@company.com",
  "widgetZesettings": "",
  "zendeskWidgetKey": "",
  "matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
  "id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
  "matomoWebsiteId": "1",
}

The above command return JSON structured like this:

{
  "data": {
    "widgetZesettings": "",
    "supportEmail": "support@company.com",
    "zendeskWidgetKey": "",
    "organization": {
      "id": "fcda8d5a-0276-4de3-908f-b3bd0aff2491"
    },
    "feedbackSlackWebhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "matomoHost": "https://myUrl-cloudmc.matomo.cloud/",
    "id": "f4be2785-ec67-474c-af3a-38ffecfa4094",
    "matomoWebsiteId": "1",
    "version": 1,
    "feedbackEmail": "feedback@company.com"
  }
}

Required
id UUID	The configured feedback settings' id.
organization.id UUID	The organization id that the feedback settings are linked to. It cannot be changed.

Optional
supportEmail string	Email address used for support requests.
feedbackEmail string	Email address used for feedback.
feedbackSlackWebhookUrl string	The slack webhook url used for feedback. Please refer to https://api.slack.com/messaging/webhooks.
version integer	The feedback settings version.
zendeskWidgetKey string	The key taken from the Zendesk admin page. Only one of supportEmail and zendeskWidgetKey can be set.
widgetZesettings string	Content of the zeSettings as a JSON for customization. Please refer to https://developer.zendesk.com/embeddables/docs/widget/settings.
matomoHost string	The Matomo analytics subdomain, ending in '.matomo.cloud'. If specified, both the host and website ID are required.
matomoWebsiteId string	The website ID which Matomo's Javascript pushes events to. If specified, both the host and website ID are required.

Delete feedback settings

DELETE /feedback/:id

Delete an existing feedback settings.

curl -X DELETE "https://cloudmc_endpoint/api/v1/feedback/f4be2785-ec67-474c-af3a-38ffecfa4094" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "taskId": "85df8dfb-b904-42dc-bb76-4824e6b50c83",
  "taskStatus": "SUCCESS"
}

Check if feedback settings is configured for an organization

GET /feedback/exists?organizationId=:id

Checks if feedback settings is configured for an organization. If the organizationId is omitted, the authenticated user's organization will be used.

# Check if feedback settings is configured
curl "https://cloudmc_endpoint/api/v1/feedback/exists?organizationId=fcda8d5a-0276-4de3-908f-b3bd0aff2491" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{}

Check if a support email is configured for an organization

GET /support/exists?organizationId=:id

Check if a support email is configured for an organization. If the organizationId is omitted, the authenticated user's organization will be used.

# Check if support email is configured
curl "https://cloudmc_endpoint/api/v1/support/exists?organizationId=fcda8d5a-0276-4de3-908f-b3bd0aff2491" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{}

Workspace Settings

Find workspace settings associated to an organization

GET /reseller/settings/workspace/find?organizationId=:id

Retrieve the workspace settings associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.

# Retrieve the workspace settings
curl "https://cloudmc_endpoint/api/v1/reseller/settings/workspace/find?organizationId=10572c3d-16e5-450f-8af8-a01e50dc52d4" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "f7ad28a8-1227-44de-9785-6dbd556f3bda",
    "version": 1,
    "detailsViewSummaryFieldsLayout": "CONDENSED",
    "supportsMultiStep": false,
  }
}

Retrieve the workspace settings associated to an organization.

Attributes
id UUID	The configured workspace settings' id.
organization.id UUID	The organization id that the workspace settings are linked to. It cannot be changed.
version integer	The workspace settings version.
detailsViewSummaryFieldsLayout enum	The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED".
supportsMultiStep boolean	If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode.

Retrieve workspace settings

GET /reseller/settings/workspace/:id

# Retrieve workspace settings
curl "https://cloudmc_endpoint/api/v1/reseller/settings/workspace/f7ad28a8-1227-44de-9785-6dbd556f3bda" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "f7ad28a8-1227-44de-9785-6dbd556f3bda",
    "version": 1,
    "detailsViewSummaryFieldsLayout": "CONDENSED",
    "supportsMultiStep": false,
  }
}

Retrieve the workspace settings associated to the workspace settings id.

Attributes
id UUID	The configured workspace settings' id.
organization.id UUID	The organization id that the workspace settings are linked to. It cannot be changed.
version integer	The workspace settings version.
detailsViewSummaryFieldsLayout enum	The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED".
supportsMultiStep boolean	If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode.

Create workspace setting

POST /reseller/settings/workspace

Create a new workspace settings.

# Creates a new workspace settings
curl -X POST "https://cloudmc_endpoint/api/v1/reseller/settings/workspace" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
 "organization": {
  "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
 },
 "detailsViewSummaryFieldsLayout": "CONDENSED",
 "supportsMultiStep": false,
}

The above command return JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
    "version": 1,
    "detailsViewSummaryFieldsLayout": "CONDENSED",
    "supportsMultiStep": false,
  }
}

Required
detailsViewSummaryFieldsLayout enum	The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED".
supportsMultiStep boolean	If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode.

Optional
organization.id UUID	The organization id that the workspace settings are linked to. If the organizationId is omitted, the authenticated user's organization will be used.

Update workspace settings

PUT /reseller/settings/workspace/:id

Updates the workspace settings of an organization.

# Updates an existing workspace settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/v1/reseller/settings/workspace/d785ffcb-9b03-478d-a49b-52a2ccedf1b8 \
   -H "MC-Api-Key: your_api_key"
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
 "organization": {
  "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
 },
 "id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
 "version": 1,
 "detailsViewSummaryFieldsLayout": "DEFAULT",
 "supportsMultiStep": false,
}

The above command return JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
    "version": 2,
    "detailsViewSummaryFieldsLayout": "DEFAULT",
    "supportsMultiStep": false,
  }
}

Required
id UUID	The configured workspace settings' id.
organization.id UUID	The organization id that the workspace settings are linked to. It cannot be changed.
detailsViewSummaryFieldsLayout enum	The layout to render summary fields in detail views. It could be either "DEFAULT" or "CONDENSED".
supportsMultiStep boolean	If true, the operation's (create/edit) forms for the service connection of an organization will appear in multi-step mode.

Delete workspace settings

DELETE /reseller/settings/workspace/:id

Delete an existing workspace settings.

curl -X DELETE "https://cloudmc_endpoint/api/v1/reseller/settings/workspace/d785ffcb-9b03-478d-a49b-52a2ccedf1b8" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "taskId": "26022b83-9797-44c0-883c-7e82ecb757e9",
  "taskStatus": "SUCCESS"
}

Custom fields

Custom fields allow administrators to define new fields on the organization and user models. This allows for additional metadata to be defined on these models.

List custom fields

GET /custom_fields

# Retrieve custom fields
curl "https://cloudmc_endpoint/rest/custom_fields?organization_id=fb0eeef9-eddd-48bc-949c-871481777ff9" \
  -h "Mc-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": [
    {
      "field": "username",
      "organization": {
        "id": "fb0eeef9-eddd-48bc-949c-871481777ff9"
      },
      "mode": "AUTOGENERATED",
      "modeOptions": {
        "autogeneratedType": "ALPHANUMERIC",
        "prefix": "ACC-",
        "length": 6
      },
      "id": "f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e",
      "type": "ORGANIZATION",
      "nameTranslations": {
        "en": "username",
        "fr": "username fr"
      },
      "descriptionTranslations": {
        "en": "username desc",
        "fr": "username desc fr"
      }
    }
  ]
}

Retrieves a list of custom fields for the given organization.

Query Params
organization_id UUID	Return only the custom fileds for the provided organization id. If not provided, will default to the user's organization.

Attributes
id UUID	The custom field's id.
organization.id UUID	The organization id that the custom field belongs to.
field String	The field you're defining, this is not the UI-facing name.
mode enum	The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED.
modeOptions.autogeneratedType enum	The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC.
modeOptions.prefix String	The prefix section of the autogenerated field.
modeOptions.length number	The length of the autogenerated section of the field.
type string	The type of model for the field. Possible values: ORGANIZATION, USER.
nameTranslations map	Map of language short codes to name translations for the field.
descriptionTranslations map	Map of language short codes to description translations for the field.

Retrieve custom field

GET /custom_fields/:id

curl "http://localhost:8080/rest/custom_fields/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e" \
  -h "Mc-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "field": "username",
    "organization": {
      "id": "fb0eeef9-eddd-48bc-949c-871481777ff9"
    },
    "mode": "AUTOGENERATED",
    "modeOptions": {
      "autogeneratedType": "ALPHANUMERIC",
      "prefix": "ACC-",
      "length": 6
    },
    "id": "f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e",
    "type": "ORGANIZATION",
    "nameTranslations": {
      "en": "username",
      "fr": "username fr",
      "es": "username es"
    },
    "descriptionTranslations": {
      "en": "username desc",
      "fr": "username desc fr"
    }
  }
}

Attributes
id UUID	The custom field's id.
organization.id UUID	The organization id that the custom field belongs to.
field String	The field you're defining, this is not the UI-facing name.
mode enum	The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED.
modeOptions.autogeneratedType enum	The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC.
modeOptions.prefix String	The prefix section of the autogenerated field.
modeOptions.length number	The length of the autogenerated section of the field.
type string	The type of model for the field. Possible values: ORGANIZATION, USER.
nameTranslations map	Map of language short codes to name translations for the field.
descriptionTranslations map	Map of language short codes to description translations for the field.

Create a custom field

POST /custom_fields

curl --request POST \
  --url https://cloudmc_endpoint/rest/custom_fields \
  --header "Content-Type: application/json" \
  --header "Mc-Api-Key: your_api_key" \
  --data "request_body"

Request body example:

{
    "type": "ORGANIZATION",
    "field": "adminEmail",
    "nameTranslations": {
        "en": "Administrator's email",
        "fr": "Courriel de l'administrateur"
    }
}

Create a new custom field.

Required
field String	The field you're defining, this is not the UI-facing name.
nameTranslations map	Map of language short codes to name translations for the field. Translations for all languages are required.
type string	The type of model for the field. Possible values: ORGANIZATION, USER. You will need the Custom fields: Manage permission to execute this operation.

Optional
mode enum	The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED. Defaults to OPTIONAL.
modeOptions.autogeneratedType enum	The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC. Defaults to ALPHANUMERIC.
modeOptions.prefix String	The prefix section of the autogenerated field.
modeOptions.length number	The length of the autogenerated section of the field. Defaults to 8.
descriptionTranslations map	Map of language short codes to description translations for the field. If passed, translations for all languages are required.
organization.id UUID	The organization id that the custom fields are linked to. It cannot be changed. If not passed, will default to the calling user's organization.

Edit a custom field

PUT /custom_fields/:id

curl --request PUT \
  --url https://cloudmc_endpoint/rest/custom_fields/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e \
  --header "Content-Type: application/json" \
  --header "Mc-Api-Key: your_api_key" \
  --data "request_body"

Request body example:

{
    "id": "f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e",
    "type": "ORGANIZATION",
    "field": "adminEmail",
    "nameTranslations": {
        "en": "Administrator's email",
        "fr": "Courriel de l'administrateur"
    },
    "descriptionTranslations": {
        "en": "username desc",
        "fr": "username desc fr"
    },
    "organization": {
        "id": "2e481375-98e6-4963-adee-5067584f1580"
    }
}

Edit an existing custom field.

Required
id UUID	The ID of the custom field.
field String	The field you're defining, this is not the UI-facing name. It cannot be changed.
nameTranslations map	Map of language short codes to name translations for the field. Translations for all languages are required.
type string	The type of model for the field. Possible values: ORGANIZATION, USER. It cannot be changed.
organization.id UUID	The organization id that the custom fields are linked to. It cannot be changed.

Optional
mode enum	The mode of the field. Possible values: REQUIRED, OPTIONAL, AUTOGENERATED. Defaults to OPTIONAL.
modeOptions.autogeneratedType enum	The format followed by the autogenerated field. Possible values: ALPHANUMERIC, ALPHABETICAL, NUMERIC. Defaults to ALPHANUMERIC.
modeOptions.prefix String	The prefix section of the autogenerated field.
modeOptions.length number	The length of the autogenerated section of the field. Defaults to 8.
descriptionTranslations map	Map of language short codes to description translations for the field. If passed, translations for all languages are required.

Delete a custom field

DELETE /custom_fields/:id

curl --request DELETE \
  --url https://cloudmc_endpoint/rest/custom_fields/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e \
  --header "Content-Type: application/json" \
  --header "Mc-Api-Key: your_api_key" 

Delete a custom field.

Quotas

Quotas are used to limit the resource usage on a service connection consumed by an organization. The primary use case for CloudMC is to enforce limited quotas on trial accounts. Quotas can target different resources. For example, number of vCPUs, allocated memory, disk size, network bandwidth, number of public IPs and more.

List quotas

GET /quotas?organization_id=:id&type=[owned|assigned]

Retrieves a list of quotas configured for a given organization. An optional type can be specified to retrieve either only the assigned or owned quotas.

Query Parameters

Optional
organization_id UUID	The organization id for which we want to get the quotas from. When not specified, the quotas for the organization the current user is associated to will be returned.
type UUID	The type of quotas. This can be assigned (quotas assigned to an organization) or owned (quotas managed by an organization). When not specified, both types are returned.

# Retrieve quotas list
curl "https://cloudmc_endpoint/api/v2/quotas" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
        {
      "ownerOrganization": {
        "name": "System",
        "id": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9"
      },
      "deleted": false,
      "quotaDetails": [
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "1c005444-6ea2-4ebc-85f7-d75f5b1943d3",
          "type": "INSTANCE_MEMORY",
          "labelKey": "quotas.memory",
          "version": 1
        },
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "674f4755-640b-4697-87bb-8a5d03704552",
          "type": "DISK_SIZE",
          "labelKey": "quotas.disk_size",
          "version": 1
        },
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "691c55b5-ecaf-434d-b509-97c4fb554d1d",
          "type": "INSTANCE_VCPUS",
          "labelKey": "quotas.vcpus",
          "version": 1
        }
      ],
      "name": "Quota Name",
      "defaultForService": true,
      "description": "Quota Description",
      "numberOfOrganizationsAppliedTo": 1,
      "id": "24330f70-9845-4851-acc0-ecd5d9b13613",
      "creationDate": "2021-01-06T19:17:06.000Z",
      "version": 1,
      "serviceConnection": {
        "serviceCode": "service-code",
        "name": "service-name",
        "id": "52fb6687-44cb-4db3-9e63-bdfabfe2faf1",
        "type": "gcp",
        "organization": {
          "id": "c5305a63-d45c-422e-9b6b-72ed1c60aedc"
        }
      },
      "defaultForTrial": true
    },
  ]
}

An array of quotas with the following attributes are returned.

Quota Attributes
id UUID	The id of the quota.
name string	The name of the quota.
description string	The description of the quota.
creationDate string	The date in ISO 8601 that the quota was created.
numberOfOrganizationsAppliedTo number	The number of organizations the quota is assigned to.
defaultForService boolean	Weather or not the quota is the default for service connections.
defaultForTrial boolean	Weather or not the quota is the default for trials.
ownerOrganization Organization	The organization that manages the quota. includes: id and name.
serviceConnection ServiceConnection	The service connection associated to the quota. includes: id and name.
quotaDetails Array [QuotaDetail]	The quota details.

The following table lists the attributes for QuotaDetail:

QuotaDetail Attributes
id UUID	The id of the quota detail.
type string	The type of quota (metric).
labelKey string	The key used for the label.
metricIdentifier string	Id matching the metric identifiers provided by the plugin writer.
ceiling number	The ceiling value (metric).
limitsize number	DEPRECATED The maximum for the type (metric).

Retrieve a quota

GET /quotas/:id

# Retrieve a specific quota
curl "https://cloudmc_endpoint/api/v2/quotas/:id" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
      "ownerOrganization": {
        "name": "System",
        "id": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9"
      },
      "deleted": false,
      "quotaDetails": [
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "1c005444-6ea2-4ebc-85f7-d75f5b1943d3",
          "type": "INSTANCE_MEMORY",
          "labelKey": "quotas.memory",
          "version": 1
        },
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "674f4755-640b-4697-87bb-8a5d03704552",
          "type": "DISK_SIZE",
          "labelKey": "quotas.disk_size",
          "version": 1
        },
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "691c55b5-ecaf-434d-b509-97c4fb554d1d",
          "type": "INSTANCE_VCPUS",
          "labelKey": "quotas.vcpus",
          "version": 1
        }
      ],
      "name": "Quota Name",
      "defaultForService": true,
      "description": "Quota Description",
      "numberOfOrganizationsAppliedTo": 1,
      "id": "24330f70-9845-4851-acc0-ecd5d9b13613",
      "creationDate": "2021-01-06T19:17:06.000Z",
      "version": 1,
      "serviceConnection": {
        "serviceCode": "service-code",
        "name": "service-name",
        "id": "52fb6687-44cb-4db3-9e63-bdfabfe2faf1",
        "type": "gcp",
        "organization": {
          "id": "c5305a63-d45c-422e-9b6b-72ed1c60aedc"
        }
      },
      "defaultForTrial": true
    }
}

A quota with the following attributes are returned.

Quota Attributes
id UUID	The id of the quota.
name string	The name of the quota.
description string	The description of the quota.
creationDate string	The date in ISO 8601 that the quota was created.
numberOfOrganizationsAppliedTo number	The number of organizations the quota is assigned to.
defaultForService boolean	Weather or not the quota is the default for service connections.
defaultForTrial boolean	Weather or not the quota is the default for trials.
ownerOrganization Organization	The organization that manages the quota. includes: id and name.
serviceConnection ServiceConnection	The service connection associated to the quota. includes: id and name.
quotaDetails Array [QuotaDetail]	The quota details.

The following table lists the attributes for QuotaDetail:

QuotaDetail Attributes
id UUID	The id of the quota detail.
type string	The type of quota (metric).
labelKey string	The key used for the label.
metricIdentifier string	Id matching the metric identifiers provided by the plugin writer.
ceiling number	The ceiling value (metric).
limitsize number	DEPRECATED The maximum for the type (metric).

Create a quota

POST /quotas

curl -X POST "https://cloudmc_endpoint/api/v2/quotas" \
   -H "MC-Api-Key: your_api_key"

Request body example: json { "name": "my-quota-name", "serviceConnection": { "id": "6abd9b5b-2aad-4732-9177-509d536c5739" }, "ownerOrganization": { "id": "976e1d4b-de6f-454b-a189-b12dd1b85112" }, "quotaDetails": [ { "metricIdentifier": "instance.cpu.count", "ceiling": 5 }, { "metricIdentifier": "disk.size.gb", "ceiling": 500 } ], "defaultForService": true, "defaultForTrial": true }

Create a quota owned by an organization for a connection.

Once created, a quota can be applied to any child organization of the quota's owner. This endpoint cannot be used to apply a quota to an organization. See POST /quotas/apply instead.

There can only be one default quota and one default trial quota for a connection. Any attempt to create a default quota, when there's already an existing one, will result in the exsting quota losing it's default status.

Required
name string	Name of the quota. Must be unique across the connection and organization.
serviceConnection ServiceConnection	Service connection associated to the quota. required: id
quotaDetails Array[QuotaDetails]	List of QuotaDetail making up the quota. A QuotaDetail represents a limit on a resource and is directly linked to a MetricDescriptor. A MetricDescriptor describes a metric offered by the plugin. For more information, consult the SDK documentation. required: metricIdentifier, ceiling
quotaDetail.metricIdentifier string	A unique identifier used to define a MetricDescriptor.
quotaDetail.ceiling number	The ceiling for this particular quota detail.

Optional
ownerOrganization Organization	Organization in which the quota will be created. Defaults to caller's organization. required: id
defaultForService Boolean	A flag denoting if this quota is the default quota for this connection. There can only be one default quota per connection/organization.
defaultForTrial Boolean	A flat denoting if this quota is the default quota for a trial. There can only be one default trial quota per connection/organization.

The responses' data field contains the created quota with its id.

Update a quota

PUT /quotas/:id

curl -X PUT "https://cloudmc_endpoint/api/v2/quotas" \
   -H "MC-Api-Key: your_api_key"

Request body example: json { "name": "my-quota-name", "description": "Quotas for trials", "quotaDetails": [ { "metricIdentifier": "instance.cpu.count", "ceiling": 5 }, { "metricIdentifier": "disk.size.gb", "ceiling": 300 } ], } Notes: - An existing quotas, owner organization and service connection cannot be changed. - The quotaDetails in the request will entirely replace the previous quotaDetails. A quotaDetail for every metric enforced by the plugin must be present. - The default flags of the quota can not be changed via the update endpoint. To update these flags, the 'quotas/:id/default' should be used. - There is an asynchronous portion of this API that will assign the updated quota limits to all currently assigned organizations and organization environments on the backend service.

Required
name string	Name of the quota. Must be unique across the connection and organization.
quotaDetails Array[QuotaDetails]	List of QuotaDetail making up the quota. A QuotaDetail represents a limit on a resource and is directly linked to a MetricDescriptor. A MetricDescriptor describes a metric offered by the plugin. For more information, consult the SDK documentation. required: metricIdentifier, ceiling
quotaDetail.metricIdentifier string	A unique identifier used to define a MetricDescriptor.
quotaDetail.ceiling number	The ceiling for this particular quota detail.

Optional
description String	The description of this quota

The responses' data field contains the updated quota.

The above command returns a JSON structured like this:

{
  "taskId": "085b008e-7ee4-444b-8092-350190786147",
  "taskStatus": "PENDING",
  "data":{
    "ownerOrganization":{
      "name":"Cox Communications",
      "id":"ca785487-5e22-4bac-ab01-187260b0d0cb"
    },
    "quotaDetails":[
        {
          "ceiling":12.0,
          "limitSize":12,
          "metricIdentifier":"workload_cpu_count",
          "metricDescriptor":{
            "metricIdentifier":"workload_cpu_count",
            "nameLabelKey":"metrics.quotas.workload_cpu_count",
            "unitLabelKey":"metrics.units.unit",
            "categoryLabelKey":"usage.stackpath.compute",
            "resourceMetricType":"GAUGE"
          },
          "id":"04d7c0cb-455a-42b2-b32a-b914c871a598",
          "type":"workload_cpu_count",
          "labelKey":"workload_cpu_count.label"
        }
    ],
    "description":"Trials assigned Edge Cloud should be assigned this quota",
    "numberOfOrganizationsAppliedTo":0,
    "creationDate":"2021-03-10T16:37:02.000Z",
    "defaultForTrial":true,
    "name":"Trial",
    "organizations":[],
    "defaultForService":false,
    "id":"6c44dc22-abf9-4fa2-b722-751848f1858e",
    "serviceConnection":{
      "serviceCode":"edge-cloud-beta",
      "organization":{
        "id":"ca785487-5e22-4bac-ab01-187260b0d0cb"
      },
      "name":"Edge Cloud Beta",
      "id":"081ffa1f-1531-4dd5-a7e2-070e560409ce",
      "type":"stackpath"
    }
  }
},

Attributes
taskId UUID	The id of the asynchronous task
taskStatus string	The current status of the asynchronous task
data Quota	The updated quota model

Delete a quota

DELETE /quotas/:id1?quota_id=:id2

Deletes an existing quota. The parameter quota_id is only required when deleting a quota that is currently assigned to an organization.

# Delete a specific quota 
curl -X DELETE "https://cloudmc_endpoint/api/v2/quotas/:id" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "taskId": "085b008e-7ee4-444b-8092-350190786147",
  "taskStatus": "SUCCESS"
}

Query Parameters

Optional
quota_id UUID	The id of the quota that will be used as a substitution for the quota that is being deleted.

Assign quota to be default quota

POST /quotas/:quota_id?service=true&trial=false

Makes a quota with :quota_id the default for the a service, trial or both. A quota can only be set as default if the quota is owned by the connection owner.

# Makes a specific quota default 
curl -X POST "https://cloudmc_endpoint/api/v2/quotas/:id/default?service=true&trial=false" \
   -H "MC-Api-Key: your_api_key"

The above command returns the updated quota when it was successfully made a default for service or trial.

Note: This endpoint only attempts to set the quota as the default, it does not remove the default flag of the quota if both service and trial query parameters are false.

{
  "data": {
      "ownerOrganization": {
        "name": "System",
        "id": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9"
      },
      "deleted": false,
      "quotaDetails": [
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "1c005444-6ea2-4ebc-85f7-d75f5b1943d3",
          "type": "INSTANCE_MEMORY",
          "labelKey": "quotas.memory",
          "version": 1
        },
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "674f4755-640b-4697-87bb-8a5d03704552",
          "type": "DISK_SIZE",
          "labelKey": "quotas.disk_size",
          "version": 1
        },
        {
          "ceiling": 1.0,
          "deleted": false,
          "limitSize": 0,
          "metricIdentifier": "metric-id",
          "id": "691c55b5-ecaf-434d-b509-97c4fb554d1d",
          "type": "INSTANCE_VCPUS",
          "labelKey": "quotas.vcpus",
          "version": 1
        }
      ],
      "name": "Quota Name",
      "defaultForService": true,
      "defaultForTrial": false,
      "description": "Quota Description",
      "numberOfOrganizationsAppliedTo": 1,
      "id": "24330f70-9845-4851-acc0-ecd5d9b13613",
      "creationDate": "2021-01-06T19:17:06.000Z",
      "version": 1,
      "serviceConnection": {
        "serviceCode": "service-code",
        "name": "service-name",
        "id": "52fb6687-44cb-4db3-9e63-bdfabfe2faf1",
        "type": "gcp",
        "organization": {
          "id": "c5305a63-d45c-422e-9b6b-72ed1c60aedc"
        }
      }
    }
}

Query Parameters

Optional
service boolean	Indicates if this quota should be made the default quota for all organizations assigned this service connection.
trial boolean	Indicates if this quota should be made the default quota for all trial organization assigned this service connection.

Activity

Whenever there is an event that occurs under the Administration panel for an organization (e.g: a user added to the organization, a role assigned to a user, etc.) an activity event is created.

The activity chart display the activity per day over the last 30 days.

List activity per organization

GET /activity

Retrieve activity count grouped by organization.

# Retrieve activity per organization
curl "https://cloudmc_endpoint/rest/organizations/activity" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
    "data": {
        "afd011d5-c7dd-4763-9892-ccbdafcd273b":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,21,23,27,0,0,3],
        "37088fe3-b266-4283-a8d0-7ff78e476760":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,7],
        "3c733655-c520-49e8-97f1-150d78d07fa5":[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,16,0,0,0,0,0]
    }
}

where the key is the organization UUID and the value is an array of integer representing daily activity. The size of the array of integer represents each day over a period of 30 days, relative to today.

Activity Logs

Activity logs are used to view the different audited operations on a given organization.

List activities

GET /activity_log

Retrieves a list of activities on a given organization. Optional parameters organizationId and only_mine can be specified to narrow the list of activities being returned.

Optional Query Parameters
organizationId UUID	The organization id for which we want to get the activities from. When not specified, the activities for the organization the current user is associated to will be returned.
only_mine boolean	Indicates if the list should include only activities performed by the current user. When not specified, the value is false.
includeSubOrgs boolean	Indicates if the list should include the sub-organizations. When not specified, the value is false.
environmentId UUID	The environment id for which we want to get the activities from. When not specified, all environments will be returned.
serviceConnectionId UUID	The environment id for which we want to get the activities from. When not specified, all environments will be returned.
userId UUID	The user id for which we want to get the activities from. When not specified, all users will be returned.
category string	The category for which we want to get the activities from. When not specified, all categories will be returned.
eventCode string	The event code for which we want to get the activities from. When not specified, all event codes will be returned.
status string	The status for which we want to get the activities from. When not specified, all statuses will be returned.
start date	The start timestamp in RFC3339 text format which which we want to get the activities from. When not specified, all events will be returned.
end date	The end timestamp in RFC3339 text format which which we want to get the activities from. When not specified, all events will be returned.

# Retrieve activity list
curl "https://cloudmc_endpoint/api/v1/activity_log" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "userLastname": "Name",
      "organizationId": "856ed38e-da4a-4f51-a7ad-e4981a44c66c",
      "requesterIp": "127.0.0.1",
      "userEmail": "username@acme.com",
      "correlationId": "caa1445a-99d4-4ec2-a6d0-13ea29f12b09",
      "id": "000598f3-d538-4b18-a5e7-964696ef8d79",
      "userOrganizationId": "a21debb5-b4ac-4e4b-9491-d0f4df6cd4f9",
      "organizationName": "Acme",
      "created": "2021-02-02T14:12:39.422Z",
      "userId": "0d7baac6-885a-4c82-9656-77529213223e",
      "eventContext": "{\"id\":null,\"firstName\":\"User\",\"lastName\":\"Name\",\"userName\":\"username@acme.com\",\"timezone\":null,\"status\":null,\"organization\":{\"id\":\"856ed38e-da4a-4f51-a7ad-e4981a44c66c\",\"name\":\"Acme\",\"isDbAuthentication\":true},\"locale\":\"en\",\"email\":\"username@acme.com\",\"lastLogin\":null,\"lastFailedLogin\":null,\"loginCount\":null,\"isTechnicalContact\":null,\"isBusinessContact\":null,\"creationDate\":null,\"tfaEnabled\":false,\"receivesEmailNotifications\":true,\"primaryRoleBinding\":{\"id\":null,\"role\":{\"id\":\"e292f73b-99ff-4677-9aeb-d98b3e196089\",\"name\":\"guest\",\"isFixed\":true,\"isSystem\":true},\"organization\":{\"id\":\"856ed38e-da4a-4f51-a7ad-e4981a44c66c\"}}}",
      "eventCode": "users.created",
      "userFirstname": "User",
      "userOrganizationName": "System",
      "category": "SYSTEM",
      "updated": "2021-02-02T14:12:43.709Z",
      "status": "SUCCESS",
      "username": "username"
    }
  ]
}

An array of activities with the following attributes are returned.

Activity Attributes
id UUID	The id of the activity.
correlationId UUID	The correlation id of the activity.
eventCode string	The human readable code for the event.
category string	The category the event belongs to.
status string	The status of the event.
created string	The date in ISO 8601 that the activity was created.
updated string	The date in ISO 8601 that the activity was created.
userId UUID	The id of the user who generated the activity.
username string	The username of the user who generated the activity.
userFirstname string	The first name of the user who generated the activity.
userLastname string	The first name of the user who generated the activity.
userEmail string	The email of the user who generated the activity.
userOrganizationId UUID	The id of the organization of the user who generated the activity.
userOrganizationName string	The name of the organization of the user who generated the activity.
organizationId UUID	The id of the organization of activity belongs to.
organizationName string	The name of the organization of activity belongs to.
requesterIp string	The ip address of the requester.
eventContext string	The escaped json event context.

List activity codes

GET /activity_log/codes

Retrieves a list of activity codes. Optional parameters organizationId and include_subs can be specified to narrow the list of activities being returned.

Optional Query Parameters
organizationId UUID	The organization id for which we want to get the activity codes from. When not specified, the activity codes for the organization the current user is associated to will be returned.
include_subs boolean	If we want to include sub-organizations activity codes.

# Retrieve activity codes
curl "https://cloudmc_endpoint/api/v1/activity_log/codes" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "SYSTEM": [
      "res_commitments.update",
      "users.autocreated",
      "environment_members.purge",
      "custom_field.deleted",
      "organizations.provision",
      "trials.converted_to_billable",
      // ...
    ]
  }
}

The list of activity codes is returned grouped by category.

Get activities summary

GET /activity_log/summary

Retrieves a summary of activities. An optional maxNumberOfItems can be passed to narrow the number of items down to be included in the summary.

Optional Query Parameters
maxNumberOfItems number	The number of items to be included in the summary.

# Retrieve activities summary
curl "https://cloudmc_endpoint/api/v1/activity_log/summary" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "userLastname": "Name",
      "organizationId": "829f0117-4b1f-49bb-8daf-ea4625ea6133",
      "environmentId": "e721bb72-e332-4745-b72f-0b15633d2823",
      "serviceConnectionName": "service-connection-name",
      "environmentName": "env-local",
      "userEmail": "username@acme.com",
      "id": "2fd514fb-bdb8-481c-ad0c-7da683181df5",
      "userOrganizationId": "829f0117-4b1f-49bb-8daf-ea4625ea6133",
      "serviceConnectionType": "stackpath",
      "organizationName": "System",
      "created": "2021-03-11T18:45:01.486Z",
      "userId": "ff17986e-8a66-4e23-8cb1-f846b1c1deb6",
      "parentId": "f5b77da1-9539-446b-8399-94c034604b0f",
      "eventContext": "{\"userName\":\"username@acme.com\",\"environmentName\":\"env-local\",\"organizationName\":\"Acme\",\"connectionName\":\"service-connection-name\"}",
      "eventCode": "environment_members.provision",
      "serviceConnectionId": "8c77bf1a-3eca-4509-b13d-005bf779df28",
      "userFirstname": "User",
      "userOrganizationName": "System",
      "category": "SYSTEM",
      "updated": "2021-03-11T18:45:02.340Z",
      "status": "SUCCESS",
      "username": "username@acme.com"
    }
  ]
}

An array of activity summaries with the following attributes are returned.

Activity Summary Attributes
id UUID	The id of the activity.
parentId UUID	The id of the parent activity.
eventCode string	The human readable code for the activity event.
category string	The category the activity event belongs to.
status string	The status of the activity event.
created string	The date in ISO 8601 that the activity was created.
updated string	The date in ISO 8601 that the activity was created.
userId UUID	The id of the user who generated the activity.
username string	The username of the user who generated the activity.
userFirstname string	The first name of the user who generated the activity.
userLastname string	The first name of the user who generated the activity.
userEmail string	The email of the user who generated the activity.
userOrganizationId UUID	The id of the organization of the user who generated the activity.
userOrganizationName string	The name of the organization of the user who generated the activity.
organizationId UUID	The id of the organization the activity belongs to.
organizationName string	The name of the organization of activity belongs to.
environmentId UUID	The id of the environment the activity belongs to.
environmentName string	The name of the environment the activity belongs to.
eventContext string	The escaped json event context.
serviceConnectionId UUID	The id of the service connection the activity belongs to.
serviceConnectionName string	The name of the service connection the activity belongs to.
serviceConnectionType string	The type of the service connection the activity belongs to.

Billing

Billing Settings

Find billing settings associated to an organization

GET /reseller/settings/billing/find?organizationId=:id

Retrieve the billing settings associated to an organization. If the organizationId is omitted, the authenticated user's organization will be used.

# Retrieve the billing settings
curl "https://cloudmc_endpoint/api/rest/reseller/settings/billing/find?organizationId=10572c3d-16e5-450f-8af8-a01e50dc52d4" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "f7ad28a8-1227-44de-9785-6dbd556f3bda",
    "version": 1,
    "daysBeforeAutoDraft": 3,
    "daysBeforeAutoApproval": 3,
    "daysBeforeAutoPayment": 5,
    "bccEmails": ["finance.support@company.com", "monitoring@company.com"],
    "daysBeforeCardWarnings": [30],
    "customerInformation": ["accountId"],
    "address": ["Address line 1", "Address line 2", "etc."],
    "termsAndConditions": "My terms and conditions...",
  }
}

Retrieve the billing settings associated to an organization.

Attributes
id UUID	The configured billing settings' id.
organization.id UUID	The organization id that the billing settings are linked to. It cannot be changed.
version integer	The billing settings version.
daysBeforeAutoDraft integer	The number of days after the billing date to continue gathering missing customer usage before the invoice is drafted. Cannot be less than 2 days.
daysBeforeAutoApproval integer	The number of days to review a draft invoice before it is automatically issued to the customer.
daysBeforeAutoPayment integer	The number of days after the invoice has been issued before the customer's credit card is automatically charged.
bccEmails Array[string]	List of email addresses to include as BCC when sending emails to customers upon billing exceptions.
daysBeforeCardWarnings Array[integer]	Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60.
customerInformation Array[string]	The list of client custom fields to display in the invoice.
address Array[string]	The address to display in the invoice. Each address field will be a row in the address block.
termsAndConditions string	The terms and conditions to display in the invoice.

Retrieve billing settings

GET /reseller/settings/billing/:id

# Retrieve billing settings
curl "https://cloudmc_endpoint/api/rest/reseller/settings/billing/f7ad28a8-1227-44de-9785-6dbd556f3bda" \
   -H "MC-Api-Key: your_api_key"

The above command returns JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "f7ad28a8-1227-44de-9785-6dbd556f3bda",
    "version": 1,
    "daysBeforeAutoDraft": 3,
    "daysBeforeAutoApproval": 3,
    "daysBeforeAutoPayment": 5,
    "bccEmails": ["finance.support@company.com", "monitoring@company.com"],
    "daysBeforeCardWarnings": [30],
    "customerInformation": ["accountId"],
    "address": ["Address line 1", "Address line 2", "etc."],
    "termsAndConditions": "My terms and conditions..."
  }
}

Retrieve the billing settings associated to the billing settings id.

Attributes
id UUID	The configured billing settings' id.
organization.id UUID	The organization id that the billing settings are linked to. It cannot be changed.
version integer	The billing settings version.
daysBeforeAutoDraft integer	The number of days after the billing date to continue gathering missing customer usage before the invoice is drafted. Cannot be less than 2 days.
daysBeforeAutoApproval integer	The number of days to review a draft invoice before it is automatically issued to the customer.
daysBeforeAutoPayment integer	The number of days after the invoice has been issued before the customer's credit card is automatically charged.
bccEmails Array[string]	List of email addresses to include as BCC when sending emails to customers upon billing exceptions.
daysBeforeCardWarnings Array[integer]	Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60.
customerInformation Array[string]	The list of client custom fields to display in the invoice.
address Array[string]	The address to display in the invoice. Each address field will be a row in the address block.
termsAndConditions string	The terms and conditions to display in the invoice.

Create billing settings

POST /reseller/settings/billing

Create new billing settings.

# Creates a new billing settings
curl -X POST "https://cloudmc_endpoint/api/rest/reseller/settings/billing" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "organization": {
    "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
  },
  "daysBeforeAutoApproval": 3,
  "daysBeforeAutoPayment": 5,
  "daysBeforeAutoDraft": 3,
  "bccEmails": ["finance.support@company.com", "monitoring@company.com"],
  "daysBeforeCardWarnings": [30],
  "customerInformation": ["accountId"],
  "address": ["Address line 1", "Address line 2", "etc."],
  "termsAndConditions": "My terms and conditions..."
}

The above command returns JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
    "version": 1,
    "daysBeforeAutoDraft": 3,
    "daysBeforeAutoApproval": 3,
    "daysBeforeAutoPayment": 5,
    "bccEmails": ["finance.support@company.com", "monitoring@company.com"],
    "daysBeforeCardWarnings": [30],
    "customerInformation": ["accountId"],
    "address": ["Address line 1", "Address line 2", "etc."],
    "termsAndConditions": "My terms and conditions..."
  }
}

Required
daysBeforeAutoDraft integer	The number of days after the billing date to continue gathering missing customer usage before the invoice is drafted. Cannot be less than 2 days.
daysBeforeAutoApproval integer	The number of days to review a draft invoice before it is automatically issued to the customer.
daysBeforeAutoPayment integer	The number of days after the invoice has been issued before the customer's credit card is automatically charged.
daysBeforeCardWarnings Array[integer]	Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60.

Optional
organization.id UUID	The organization id that the billing settings are linked to. If the organizationId is omitted, the authenticated user's organization will be used.
customerInformation Array[string]	The list of client custom fields to display in the invoice.
address Array[string]	The address to display in the invoice. Each address field will be a row in the address block.
termsAndConditions string	The terms and conditions to display in the invoice.
bccEmails Array[string]	List of email addresses to include as BCC when sending emails to customers upon billing exceptions.

Update billing settings

PUT /reseller/settings/billing/:id

Updates the billing settings of an organization.

# Updates an existing billing settings for an organization
curl -X PUT "https://cloudmc_endpoint/api/rest/reseller/settings/billing/d785ffcb-9b03-478d-a49b-52a2ccedf1b8 \
   -H "MC-Api-Key: your_api_key"
   -H "Content-Type: application/json" \
   -d "request-body"

Request body example:

{
  "organization": {
    "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
  },
  "id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
  "version": 1,
   "daysBeforeAutoDraft": 3,
  "daysBeforeAutoApproval": 3,
  "daysBeforeAutoPayment": 5,
  "bccEmails": ["finance.support@company.com", "monitoring@company.com"],
  "daysBeforeCardWarnings": [30],
  "customerInformation": ["accountId"],
  "address": ["Address line 1", "Address line 2", "etc."],
  "termsAndConditions": "My terms and conditions..."
}

The above command returns JSON structured like this:

{
  "data": {
    "organization": {
      "id": "10572c3d-16e5-450f-8af8-a01e50dc52d4"
    },
    "id": "d785ffcb-9b03-478d-a49b-52a2ccedf1b8",
    "version": 2,
    "daysBeforeAutoDraft": 3,
    "daysBeforeAutoApproval": 3,
    "daysBeforeAutoPayment": 5,
    "bccEmails": ["finance.support@company.com", "monitoring@company.com"],
    "daysBeforeCardWarnings": [30],
    "customerInformation": ["accountId"],
    "address": ["Address line 1", "Address line 2", "etc."],
    "termsAndConditions": "My terms and conditions..."
  }
}

Required
id UUID	The configured billing settings' id.
organization.id UUID	The organization id that the billing settings are linked to. It cannot be changed.
daysBeforeAutoDraft integer	The number of days after the billing date to continue gathering missing customer usage before the invoice is drafted. Cannot be less than 2 days.
daysBeforeAutoApproval integer	The number of days to review a draft invoice before it is automatically issued to the customer.
daysBeforeAutoPayment integer	The number of days after the invoice has been issued before the customer's credit card is automatically charged.
daysBeforeCardWarnings Array[integer]	Specify the number of days before notifying a customer of an expiring credit card. You can specify 1 to 5 values between 1 and 60.

Optional
customerInformation Array[string]	The list of client custom fields to display in the invoice.
address Array[string]	The address to display in the invoice. Each address field will be a row in the address block.
termsAndConditions string	The terms and conditions to display in the invoice.
bccEmails Array[string]	List of email addresses to include as BCC when sending emails to customers upon billing exceptions.

Delete billing settings

DELETE /reseller/settings/billing/:id

Delete an existing billing settings.

curl -X DELETE "https://cloudmc_endpoint/api/rest/reseller/settings/billing/d785ffcb-9b03-478d-a49b-52a2ccedf1b8" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "taskId": "26022b83-9797-44c0-883c-7e82ecb757e9",
  "taskStatus": "SUCCESS"
}

Billing providers

The billing providers are the different payment processing tools that can be used to charge organizations.

List billing providers

GET /billing_providers

Retrieves a list of billing providers configured in the system.

# Retrieve billing providers list
curl "https://cloudmc_endpoint/rest/billing_providers" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "f26e66a4-755c-4867-b565-ad68aa515237",
      "organization": {
        "id": "23910576-d29f-4c14-b663-31d728ff49a5"
      },
      "name": "Chase Credit Card (Dev)",
      "type": "CREDIT_CARD",
      "providerType": "chaseCreditCard",
      "createdDate": "2021-05-07T19:21:20Z",
      "updatedDate": "2021-05-07T19:21:20Z",
      "defaultForType": true,
      "configurationAttributes": {
        "creditCards": "American Express,Mastercard,Visa,Discover"
      }
    }
  ]
}

Attributes
id UUID	The UUID of the billing provider.
organization.id UUID	UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller.
name string	The name of the billing provider object.
type string	The type of billing provider. Possible values are: CREDIT_CARD.
providerType string	The provider for the associated type.
createdDate string	The date the billing provider was created.
updatedDate string	The last date the billing provider was updated.
defaultForType boolean	If this billing provider is the default for the specified type.
configurationAttributes Object	The configuration attribute associated to the provider type. See possible values

Retrieve a billing provider

GET /billing_providers/:id

Retrieve a billing provider's details.

# Retrieve a billing provider's details
curl "https://cloudmc_endpoint/rest/billing_providers/f26e66a4-755c-4867-b565-ad68aa515237" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "f26e66a4-755c-4867-b565-ad68aa515237",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "name": "Chase Credit Card (Dev)",
    "type": "CREDIT_CARD",
    "providerType": "chaseCreditCard",
    "createdDate": "2021-05-07T19:21:20Z",
    "updatedDate": "2021-05-07T19:21:20Z",
    "defaultForType": true,
    "configurationAttributes": {
      "creditCards": "American Express,Mastercard,Visa,Discover"
    }
  }
}

Attributes
id UUID	The UUID of the billing provider.
organization.id UUID	UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller.
name string	The name of the billing provider object.
type string	The type of billing provider. Possible values are: CREDIT_CARD.
providerType string	The provider for the associated type.
createdDate string	The date the billing provider was created.
updatedDate string	The last date the billing provider was updated.
defaultForType boolean	If this billing provider is the default for the specified type.
configurationAttributes Object	The configuration attribute associated to the provider type. See possible values

Create a billing provider

POST /billing_providers

Create a new billing provider.

# Creates a new billing provider
curl -X POST "https://cloudmc_endpoint/rest/billing_providers" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": "Chase Credit Card (Dev)",
  "organization": {
    "id": "23910576-d29f-4c14-b663-31d728ff49a5"
  },
  "type": "CREDIT_CARD",
  "providerType": "chaseCreditCard",
  "defaultForType": false,
  "configurationAttributes": {
    "creditCards": "Visa, Mastercard, American Express, Discover"
  }
}

The above command return JSON structured like this:

{
  "data": {
    "createdDate": "2021-05-17T19:59:33.387453Z",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "name": "testing API",
    "configurationAttributes": {
      "creditCards": "Visa, Mastercard, American Express, Discover"
    },
    "defaultForType": false,
    "id": "8db7cd13-b309-4fb9-b022-1632dbd165d0",
    "updatedDate": "2021-05-17T19:59:33.387477Z",
    "type": "CREDIT_CARD",
    "providerType": "chaseCreditCard"
  }
}

Required
name string	The name of the billing provider object.
organization.id UUID	UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller.
type string	The type of billing provider. Possible values are: CREDIT_CARD.
providerType string	The provider for the associated type.
configurationAttributes Object	The configuration attribute associated to the provider type. See possible values

Optional
defaultForType UUID	If this billing provider is the default for the specified type.

Update billing provider

PUT /billing_providers/:id

Update an existing billing provider.

# Updates an existing billing provider
curl -X PUT "https://cloudmc_endpoint/rest/billing_providers/c84cfe41-929b-47c9-bde4-b55a10bd2774" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "name": "Chase Credit Card (Dev)",
  "organization": {
    "id": "23910576-d29f-4c14-b663-31d728ff49a5"
  },
  "type": "CREDIT_CARD",
  "providerType": "chaseCreditCard",
  "defaultForType": false,
  "configurationAttributes": {
    "creditCards": "Visa, Mastercard, American Express, Discover"
  }
}

The above command return JSON structured like this:

{
  "data": {
    "createdDate": "2021-05-17T20:32:07Z",
    "organization": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "name": "Chase Credit Card (Dev)",
    "configurationAttributes": {
      "creditCards": "Visa, Mastercard, American Express"
    },
    "defaultForType": false,
    "id": "c84cfe41-929b-47c9-bde4-b55a10bd2774",
    "updatedDate": "2021-05-17T21:09:49Z",
    "type": "CREDIT_CARD",
    "providerType": "chaseCreditCard"
  }
}

Required
name string	The name of the billing provider object.
organization.id UUID	UUID of the organization to which belongs the billing provider. This can only be a organization which is root or reseller.
type string	The type of billing provider. Possible values are: CREDIT_CARD.
providerType string	The provider for the associated type.
configurationAttributes Object	The configuration attribute associated to the provider type. See possible values

Optional
defaultForType boolean	If this billing provider is the default for the specified type.

Provider type configuration attribute

Here are the attributes for the CREDIT_CARD providers.

Provider	Attributes
all	creditCards string	The type of credit card accepted. This is a comma separated field. Possible values are 'Visa', 'Mastercard', 'American Express', 'Discover.
chaseCreditCard	hostname string	Hosted payment hostname.
chaseCreditCard	secureId string	Unique value identifying the client’s Hosted Payment account.
chaseCreditCard	secureToken string	Unique value associated with Hosted Payment account.
chaseCreditCard	cssURL string	Sets the URL of the CSS file used to style the payment form. This value overrides the URL set in the Hosted Payment Page Admin screen.
chaseCreditCard	orbitalHostname string	Orbital API hostname.
chaseCreditCard	orbitalUsername string	Orbital Connection Username set up on Orbital Gateway.
chaseCreditCard	orbitalPassword string	Orbital Connection Password used in conjunction with Orbital Username.
chaseCreditCard	orbitalMerchantId string	Orbital API merchant ID.
chaseCreditCard	orbitalMerchantTerminal string	Orbital API merchant terminal ID.
chaseCreditCard	orbitalMerchantBin string	Orbital API merchant BIN number.

Delete a billing provider

DELETE /billing_providers/:id

curl --request DELETE \
  --url https://cloudmc_endpoint/rest/billing_providers/f9a2b02b-7d67-4910-8353-c4bfcbdeaa7e \
  --header "Content-Type: application/json" \
  --header "Mc-Api-Key: your_api_key" 

Delete a billing provider.

Tax providers

A tax provider enables a reseller to map tax codes to monetization products. The tax code provider will ensure that invoices include taxes based on the billing details (i.e. billing address) and mapping of tax codes to product offerings provided by the reseller.

List tax providers

GET /tax_providers

Retrieves a list of tax providers configured for a reseller.

Note: You must have the Reseller billing permission on the target reseller. If the caller does not have the correct permissions or the reseller with the ID provided does not exist then a 404 Not Found response will be returned.

# Retrieve tax providers
curl "https://cloudmc_endpoint/rest/tax_providers?reseller_id=23910576-d29f-4c14-b663-31d728ff49a5" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "f26e66a4-755c-4867-b565-ad68aa515237",
      "reseller": {
        "id": "23910576-d29f-4c14-b663-31d728ff49a5"
      },
      "type": "AVALARA",
      "createdDate": "2021-05-07T19:21:20Z",
      "updatedDate": "2021-05-07T19:21:20Z",
      "configurationAttributes": {
        "companyId": "acme",
        "username": "username",
        "password" "password"
      }
    }
  ]
}

Attributes
id UUID	The UUID of the tax provider.
reseller.id UUID	UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller).
type string	The type of tax provider. Possible values are: AVALARA.
state *enum"	The state of the tax provider. Possible values are: CONFIGURED, CONFIGURING, ERROR.
createdDate string	The date the tax provider was created.
updatedDate string	The last date the tax provider was updated.
configurationAttributes Object	The configuration attributes associated to the provider type. This depends on the provider type.

Get a tax provider

GET /tax_providers/:id

Retrieves a tax provider's details.

Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider for the given ID does not exist, then a 404 Not Found response will be returned.

# Retrieve a specific tax provider
curl "https://cloudmc_endpoint/rest/tax_providers/f26e66a4-755c-4867-b565-ad68aa515237" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "f26e66a4-755c-4867-b565-ad68aa515237",
    "reseller": {
      "id": "23910576-d29f-4c14-b663-31d728ff49a5"
    },
    "type": "AVALARA",
    "createdDate": "2021-05-07T19:21:20Z",
    "updatedDate": "2021-05-07T19:21:20Z",
    "configurationAttributes": {
      "companyId": "acme",
      "username": "username",
      "password" "password"
    }
  }
}

Attributes
id UUID	The UUID of the tax provider.
reseller.id UUID	UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller).
type string	The type of tax provider. Possible values are: AVALARA.
state *enum"	The state of the tax provider. Possible values are: CONFIGURED, CONFIGURING, ERROR.
createdDate string	The date the tax provider was created.
updatedDate string	The last date the tax provider was updated.
configurationAttributes Object	The configuration attributes associated to the provider type. This depends on the provider type.

Get tax codes for a given reseller organization

GET /tax_providers/:id/tax-codes

Retrieves a list of tax codes from the configured tax provider for a reseller organization.

Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider is not configured for the given organization ID or the organization does not exist, then a 404 Not Found response will be returned. The required ID in the URL is the ID of the reseller organization for which the tax codes are being fetched.

# Retrieve tax codes for a given organization
curl "https://cloudmc_endpoint/rest/tax_providers/f26e66a4-755c-4867-b565-ad68aa515237/tax-codes" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "code": "SW054101",
      "description": "Cloud Services - SaaS - Service Agreement - Database Products"
    },
    {
      "code": "SW053004",
      "description": "Cloud Services - SaaS - License Agreement - for business use only"
    },
    {
      "code": "SW056003",
      "description": "Cloud Services / Platform as a Service (PaaS)"
    }
  ]
}

Attributes
code string	The code of the tax.
description string	The description of the tax code.

Create a tax provider

POST /tax_providers/

Creates a tax provider for the given reseller

Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider for the given ID does not exist, then a 404 Not Found response will be returned.

# Create a tax provider
curl "https://cloudmc_endpoint/rest/tax_providers" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "reseller": {
    "id": "174cace2-ad04-47c7-9429-e180bb44cf71"
  },
  "type": "AVALARA",
  "configurationAttributes": {
    "environment": "Production",
    "username": "email@cloudops.com",
    "password": "password",
    "companyId": "1148191"
  },
  "address": {
    "lineOne": "420 GUY ST",
    "lineTwo": "",
    "city": "MONTREAL",
    "province": "QC",
    "country": "CA",
    "postalCode": "H3J 1S6"
  }
}

The above command returns a JSON structured like this:

{
  "data": {
    "address": {
      "country": "CA",
      "lineTwo": "",
      "province": "QC",
      "city": "MONTREAL",
      "postalCode": "H3J 1S6",
      "lineOne": "420 GUY ST"
    },
    "reseller": {
      "id": "174cace2-ad04-47c7-9429-e180bb44cf71"
    },
    "configurationAttributes": {
      "environment": "Production",
      "password": "password",
      "companyId": "1148191",
      "username": "email@cloudops.com"
    },
    "id": "961a2b96-0a6a-4bb4-9e32-59a3dcc555aa",
    "state": "CONFIGURING",
    "type": "AVALARA"
  },
  "taskId": "eea0cf4d-47fc-4f5d-b227-863502486192",
  "taskStatus": "PENDING"
}

Attributes
reseller.id UUID	UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller).
type string	The type of tax provider. Possible values are: AVALARA.
configurationAttributes Object	The configuration attributes associated to the provider type. This depends on the provider type.
address.lineOne string	The address line 1 of the reseller.
address.lineTwo string	The address line 2 of the reseller.
address.city string	The city name of the reseller.
address.province string	The province of the reseller.
address.country string	The country of the reseller.
address.postalCode string	The postal code of the reseller.

Update a tax provider

PUT /tax_providers/:id

Updates a tax provider for the given reseller

Note: You must have the Reseller billing permission on the owner of the tax provider requested. If the caller does not have the correct permissions or the tax provider for the given ID does not exist, then a 404 Not Found response will be returned.

# Update a tax provider
curl "https://cloudmc_endpoint/rest/tax_providers/961a2b96-0a6a-4bb4-9e32-59a3dcc555aa" \
   -H "MC-Api-Key: your_api_key"

Request body example:

{
  "reseller": {
    "id": "174cace2-ad04-47c7-9429-e180bb44cf71"
  },
  "type": "AVALARA",
  "configurationAttributes": {
    "environment": "Production",
    "username": "email@cloudops.com",
    "password": "password",
    "companyId": "1148191"
  },
  "address": {
    "lineOne": "420 GUY ST",
    "lineTwo": "",
    "city": "MONTREAL",
    "province": "QC",
    "country": "CA",
    "postalCode": "H3J 1S6"
  }
}

The above command returns a JSON structured like this:

{
  "data": {
    "address": {
      "country": "CA",
      "lineTwo": "",
      "province": "QC",
      "city": "MONTREAL",
      "postalCode": "H3J 1S6",
      "lineOne": "420 GUY ST"
    },
    "reseller": {
      "id": "174cace2-ad04-47c7-9429-e180bb44cf71"
    },
    "createdDate": "2021-05-07T19:21:20Z",
    "updatedDate": "2021-05-07T19:21:20Z",
    "configurationAttributes": {
      "environment": "Production",
      "password": "password",
      "companyId": "1148191",
      "username": "email@cloudops.com"
    },
    "id": "961a2b96-0a6a-4bb4-9e32-59a3dcc555aa",
    "state": "CONFIGURING",
    "type": "AVALARA"
  },
  "taskId": "eea0cf4d-47fc-4f5d-b227-863502486192",
  "taskStatus": "PENDING"
}

Attributes
reseller.id UUID	UUID of the reseller to which the tax provider belongs (AKA an organization id that is a reseller).
type string	The type of tax provider. Possible values are: AVALARA.
configurationAttributes Object	The configuration attributes associated to the provider type. This depends on the provider type.
address.lineOne string	The address line 1 of the reseller.
address.lineTwo string	The address line 2 of the reseller.
address.city string	The city name of the reseller.
address.province string	The province of the reseller.
address.country string	The country of the reseller.
address.postalCode string	The postal code of the reseller.
createdDate string	The date the tax provider was created.
updatedDate string	The last date the tax provider was updated.

Verify an organization's reseller tax configuration

GET /tax_providers/:id/tax-provider-configured

This endpoint verifies whether or not a given organization's reseller parent organization has configured a tax provider.

# Verify an organization's reseller tax configuration
curl "https://cloudmc_endpoint/rest/tax_providers/961a2b96-0a6a-4bb4-9e32-59a3dcc555aa/tax-provider-configured" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this: json { "data": true }

Path Parameters
id UUID	The id of the organization to verify the tax configuration for.

Attributes
data boolean	Whether or not the specified organization's reseller parent has a tax provider configured

Custom navigation

Custom navigation API allows to customize the navigation per-reseller. Most notably it allows to customize what tabs are shown to a user in the main menu.

List custom navigation

GET /navigation

curl --request GET \
  --url http://cloudmc_endpoint/rest/navigation/:id \
  --header 'Content-Type: application/json' \
  --header 'Mc-Api-Key: your_api_key'

The above command returns JSON structured like this:

{
  "data": [
    {
      "reseller": {
        "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
      },
      "alwaysShowOrgPicker": false,
      "id": "f8663571-1d84-4d48-bb86-d4e2a14ea9f9",
      "enabled": true
    }
  ]
}

Retrieves a list of custom navigations. Since there is only one custom navigation per reseller this list will either be of length 1 or 0.

Query Params
organization_id UUID	Return only the custom navigation for the provided organization id. If not provided, will default to the calling user's organization. Must be a reseller organization.

Attributes
id UUID	The custom navigations's id.
reseller.id UUID	The organization id that the custom field belongs to.
enabled boolean	Whether not custom navigation is enabled on the reseller.
alwaysShowOrgPicker boolean	Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization.

Get custom navigation

GET /navigation/:id

curl --request GET \
  --url http://cloudmc_endpoint/rest/navigation/f8663571-1d84-4d48-bb86-d4e2a14ea9f9 \
  --header 'Content-Type: application/json' \
  --header 'Mc-Api-Key: your_api_key'

The above command returns JSON structured like this:

{
  "data": {
    "reseller": {
      "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
    },
    "tabs": [
      {
        "name": {
          "en": "system en",
          "fr": "system fr"
        },
        "rank": 0,
        "id": "e4f527bf-9de6-4055-9ede-6949d01156f9",
        "tag": {
          "en": "tag en",
          "fr": "tag fr"
        },
        "type": "SYSTEM",
        "key": "/users"
      },
      {
        "name": {
          "en": "system en",
          "fr": "sytem fr"
        },
        "rank": 1,
        "id": "125e296a-ae59-4cd7-8d5b-0cf354cbb1cc",
        "type": "COMING_SOON"
      }
    ],
    "alwaysShowOrgPicker": false,
    "id": "f8663571-1d84-4d48-bb86-d4e2a14ea9f9",
    "enabled": true
  }
}

Retrieves a detailed custom navigation by id.

Query Params
organization_id UUID	Return only the custom navigation for the provided organization id. If not provided, will default to the calling user's organization. Must be a reseller organization.

Attributes
id UUID	The custom navigations's id.
reseller.id UUID	The organization id that the custom field belongs to.
enabled boolean	Whether not custom navigation is enabled on the reseller.
alwaysShowOrgPicker boolean	Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization.
tabs Array[Object]	List of tabs, the the order they should be displayed in a the menu.
tabs.name Object	Mapped object containing the tab name in different languages.
tabs.tooltip Object	Mapped object containing the tab's tooltip name in different languages.
tabs.tag Object	Mapped object containing the tab's tag name in different languages.
tabs.rank int	The order in which the tab will be displayed in the menu.
tabs.type String	Valid values are SERVICE, SYSTEM and COMING_SOON.
tabs.icon String	A string representing a css icon class.
tabs.serviceConnection UUID	The service connection id for a tab of type SERVICE.
tabs.workspace String	The workspace name for a tab of type SERVICE.
tabs.key String	The view key for a tab of type SYSTEM.
tabs.skipEnvironmentList boolean	Skip the environment list if there is a single environment associated with the service tab. Configurable for a tab of type SERVICE.
tabs.showSubTabs boolean	Whether or not to show the subtabs, as defined by the plugin, underneath the menu tab. Configurable for a tab of type SERVICE.
tabs.retainEnvironment boolean	Retain the selected environment when navigating between tabs with the same service connection. Configurable for a tab of type SERVICE.

Create custom navigation

POST /navigation

  --request POST \
  --url http://cloudmc_endpoint/rest/navigation \
  --header 'Content-Type: application/json' \
  --header 'Mc-Api-Key: your_api_key' \
  --data '{
  "enabled": true,
  "reseller": {
    "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
  },
  "tabs": [
    {
      "type": "SYSTEM",
      "key": "users",
      "name": {
        "en": "Users",
        "fr": "Usagers"
      }
    },
    {
      "type": "SERVICE",
      "name": {
        "en": "Edge compute",
        "fr": "Edge compute"
      },
      "serviceConnection": {
        "id": "2d49e70f-e4f8-43e3-b730-92328174214sa21"
      },
      "workspace": "compute",
      "showSubTabs": true,
      "skipEnvironmentPicker": true
    },
    {
      "type": "COMING_SOON",
      "name": {
        "en": "hot new feature",
        "fr": "hot new feature fr"
      }
    }
  ]
}'

The above command returns JSON structured like this:

{
  "data": {
    "reseller": {
      "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
    },
    "tabs": [
      {
        "name": {
          "en": "Users",
          "fr": "Usagers"
        },
        "rank": 0,
        "id": "d95a83ed-ba25-432b-94c9-9d59e82f8284",
        "type": "SYSTEM",
        "key": "users"
      },
      {
        "workspace": "compute",
        "name": {
          "en": "Edge compute",
          "fr": "Edge compute"
        },
        "icon": "fa fa-server",
        "rank": 1,
        "skipEnvironmentPicker": true,
        "id": "6080bdb2-ceda-4774-aa28-c7f98cd804a4",
        "showSubTabs": true,
        "type": "SERVICE",
        "serviceConnection": {
          "id": "2d49e70f-e4f8-43e3-b730-92328174214sa21"
        }
      },
      {
        "name": {
          "en": "hot new feature",
          "fr": "hot new feature fr"
        },
        "rank": 2,
        "id": "cb36c538-6f6b-47af-bfa8-daad56ce58ed",
        "type": "COMING_SOON"
      }
    ],
    "alwaysShowOrgPicker": false,
    "id": "e80adf4d-5401-4cff-b393-93a7f10f4d71",
    "enabled": true
  }
}

Optional
reseller.id UUID	The organization id that the custom field belongs to. If not provided defaults to caller's organization.
enabled boolean	Whether not custom navigation is enabled on the reseller. Defaults to false.
alwaysShowOrgPicker boolean	Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization. Defaults to false.
tabs Array[Object]	List of tabs, in the order they should be displayed in the menu.
tabs.type Object	Required in tab object. Valid values are SERVICE, SYSTEM and COMING_SOON.
tabs.name Object	Required in tab object. Mapped object containing the tab name in different languages. Need to specify all languages for target reseller's branding.
tabs.tooltip Object	Mapped object containing the tab's tooltip name in different languages. Need to specify all languages for target reseller's branding.
tabs.tag Object	Mapped object containing the tab's tag name in different languages. Need to specify all languages for target reseller's branding.
tabs.icon String	A string representing a css icon class.
tabs.serviceConnection UUID	Required if type SERVICE. The service connection id for a tab of type SERVICE.
tabs.workspace String	Required if type SERVICE. The workspace name for a tab of type SERVICE.
tabs.key String	Required if type SYSTEM. The view key for a tab of type SYSTEM.
tabs.skipEnvironmentList boolean	Skip the environment list if there is a single environment associated with the service tab. Configurable for a tab of type SERVICE.
tabs.showSubTabs boolean	Whether or not to show the subtabs, as defined by the plugin, underneath the menu tab. Configurable for a tab of type SERVICE.
tabs.retainEnvironment boolean	Retain the selected environment when navigating between tabs with the same service connection. Configurable for a tab of type SERVICE.

Update custom navigation

PUT /navigation/:id

curl --request PUT \
  --url http://cloudmc_endpoint/rest/navigation/e80adf4d-5401-4cff-b393-93a7f10f4d71 \
  --header 'Content-Type: application/json' \
  --header 'Mc-Api-Key: your_api_key' \
  --data '{
    "id": "e80adf4d-5401-4cff-b393-93a7f10f4d71",
    "reseller": {
        "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
    },
    "enabled": false,
    "tabs": []
}'

The above command returns JSON structured like this:

{
  "data": {
    "reseller": {
      "id": "c869e848-6fb3-4850-af3d-42c5666f2c78"
    },
    "tabs": [],
    "alwaysShowOrgPicker": false,
    "id": "e80adf4d-5401-4cff-b393-93a7f10f4d71",
    "enabled": false
  }
}

Update a custom navigation.

Required
id UUID	The id of the custom navigation. Cannot be changed.
reseller.id UUID	The organization id that the custom field belongs to. If not provided defaults to caller's organization.

Optional
enabled boolean	Whether not custom navigation is enabled on the reseller. Defaults to false.
alwaysShowOrgPicker boolean	Whether or not to always show the organization picker in the sidebar, even when the user has access to only a single organization. Defaults to false.
tabs Array[Object]	List of tabs, in the order they should be displayed in a the menu. Replaces all tabs currently set on the object.
tabs.type Object	Required in tab object. Valid values are SERVICE, SYSTEM and COMING_SOON.
tabs.name Object	Required in tab object. Mapped object containing the tab name in different languages. Need to specify all languages for target reseller's branding.
tabs.tooltip Object	Mapped object containing the tab's tooltip name in different languages. Need to specify all languages for target reseller's branding.
tabs.tag Object	Mapped object containing the tab's tag name in different languages. Need to specify all languages for target reseller's branding.
tabs.icon String	A string representing a css icon class.
tabs.serviceConnection UUID	Required if type SERVICE. The service connection id for a tab of type SERVICE.
tabs.workspace String	Required if type SERVICE. The workspace name for a tab of type SERVICE.
tabs.key String	Required if type SYSTEM. The view key for a tab of type SYSTEM.
tabs.skipEnvironmentList boolean	Skip the environment list if there is a single environment associated with the service tab. Configurable for a tab of type SERVICE.
tabs.showSubTabs boolean	Whether or not to show the subtabs, as defined by the plugin, underneath the menu tab. Configurable for a tab of type SERVICE.
tabs.retainEnvironment boolean	Retain the selected environment when navigating between tabs with the same service connection. Configurable for a tab of type SERVICE.

Delete custom navigation

DELETE /navigation/:id

curl --request DELETE \
  --url http://cloudmc_endpoint/rest/navigation/e80adf4d-5401-4cff-b393-93a7f10f4d71 \
  --header 'Mc-Api-Key: you_api_key'

The above command returns JSON structured like this:

{
  "taskId": "96bb7528-dc19-48b5-b713-9e55c7664aaf",
  "taskStatus": "SUCCESS"
}

Delete's a custom navigation configuration.

Metrics

The metrics API can be queried to obtain metrics data that is pushed by the service to CloudMC metric data store.

Retrieve Metrics for a Specified Interval

GET /metrics/{serviceCode}/{metricId}

Retrieves metrics for a given metric id in a specified interval

# Retrieve metrics for a given interval
curl "https://cloudmc_endpoint/api/v1/metrics/stackpath-cox-dev/ingress_bandwidth?startDate=2021-08-12T10:50:46.386Z&endDate=2021-08-15T10:50:46.386Z&size=12&unit=hours&entityId=1923471a-6a72-474d-9e19-63075bc1020b" \
   -H "MC-Api-Key: your_api_key"

The above command returns a JSON structured like this:

{
    "data": {
        "ingress_bandwidth": [
            {
                "entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
                "label": "2021-08-12T12:00:00.000",
                "value": 0.27
            },
            {
                "entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
                "label": "2021-08-13T00:00:00.000",
                "value": 0.29
            },
            {
                "entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
                "label": "2021-08-13T12:00:00.000",
                "value": 0.25
            },
            {
                "entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
                "label": "2021-08-14T00:00:00.000",
                "value": 0.37
            },
            {
                "entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
                "label": "2021-08-14T12:00:00.000",
                "value": 0.26
            },
            {
                "entityId": "1923471a-6a72-474d-9e19-63075bc1020b",
                "label": "2021-08-15T00:00:00.000",
                "value": 0.21
            }
        ]
    }
}

Path Parameters
serviceCode string	A globally unique code that identifies this service connection..
metricId string	A unique identifier used to define a MetricDescriptor.

Required Query Parameters
startDate Date	The start date of the interval to query metrics for. The date must be in a valid ISO-8601 format. The start date must be provided to query this endpoint.
endDate Date	The start date of the interval to query metrics for. The date must be in a valid ISO-8601 format. The end date must be provided to query this endpoint.

Optional Query Parameters
environment string	The name of the environment to query metrics for.
aggregationType string	How the queried metrics should be aggregated. The possible values are sum, count, min, max, avg (average). When not provided, the default value used is average.
size integer	The size of the data points granularity in the response. The size must be a positive integer value. When combined with unit, this forms an expression similar to 1 hour, or 1 day, etc. The default value used is 5.
unit string	The unit of the data points granularity in the response. The unit must be a valid Java Chronounit. The default value is MINUTES.
entityType String	The type of entity to query metrics for. When provided, only those metric records that have the provided entityType are aggregated.
entityId UUID	The id of the entity to query metrics for. When provided, only those metric records that have the provided entityId are aggregated.

Attributes
label UUID	The UTC timestamp used to label the value returned by the query.
value Number	The value of the metric at the given timestamp.
entityId UUID	The id of the entity metrics data was queried for.

CloudStack plugin

The CloudStack plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. While each operation has its own validation and required fields, all operations need to specify the service code and environment in which they should be carried out. The following example URL describes how to specify this information for all entities.

https://cloudmc_endpoint/api/v1/services/:service_code/:environment_name/:entity_type

Compute

Instances

Deploy and manage your instances.

For information regarding bare metal instances, please see bare metal instances.

List instances

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "9db8ff2f-b49b-466d-a2f3-c1e6def408f4",
      "name": "my_instance",
      "affinityGroupIds": [],
      "computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
      "computeOfferingName": "1vCPU.512MB",
      "cpuCount": 1,
      "hostname": "my_instance",
      "imageId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
      "imageName": "CentOS 6.8 PV",
      "ipAddress": "10.164.212.68",
      "isPasswordEnabled": true,
      "macAddress": "02:00:2b:67:00:30",
      "memoryInMB": 512,
      "networkId": "d5a68379-a9ee-404f-9492-a1964b374d6f",
      "networkName": "Web-test_area",
      "state": "Running",
      "username": "cca-user",
      "vpcId": "9eb1592c-f92f-4ddd-9799-b58caf896328",
      "vpcName": "prod-VPC",
      "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
      "zoneName": "QC-1"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/instances

Retrieve a list of all instances in a given environment.

Attributes
id UUID	The id of the instance
name string	The display name of the instance
affinityGroupIds Array[UUID]	The id(s) of the affinity groups to which the instance is associated.
computeOfferingId UUID	The compute offering id of the instance
computeOfferingName string	The compute offering name of the instance
cpuCount int	The number of vCPUs associated with the instance's compute offering
hostname string	The host name of the instance
imageId UUID	The image id of the instance
imageName string	The image name of the instance
ipAddress string	The instance's private IPv4 address
isPasswordEnabled boolean	Indicate whether a password can be used for remote connections
macAddress string	The instance's MAC address
memoryInMB int	The number of megabytes associated with the instance's compute offering
networkId UUID	The id of the network where instance is deployed
networkName string	The name of the network where instance is deployed
state string	The current state of the instance
username string	The username that can be used to connect to the instance
vpcId UUID	The id of the associated VPC
vpcName string	The name of associated VPC
zoneId UUID	The id of the zone where instance is deployed
zoneName string	The name of associated zone

Retrieve an instance

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "9db8ff2f-b49b-466d-a2f3-c1e6def408f4",
    "name": "backup_instance",
    "affinityGroupIds": [],
    "computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
    "computeOfferingName": "1vCPU.512MB",
    "cpuCount": 1,
    "hostname": "backup_instance",
    "imageId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
    "imageName": "CentOS 6.8 PV",
    "ipAddress": "10.164.212.68",
    "isPasswordEnabled": true,
    "macAddress": "02:00:2b:67:00:30",
    "memoryInMB": 512,
    "networkId": "d5a68379-a9ee-404f-9492-a1964b374d6f",
    "networkName": "Web-test_area",
    "state": "Running",
    "userData": "",
    "username": "cca-user",
    "vpcId": "9eb1592c-f92f-4ddd-9799-b58caf896328",
    "vpcName": "prod-VPC",
    "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
    "zoneName": "QC-1",
    "publicIps": [{
      "id": "7a204b7f-1039-4867-8971-c1e4f778ef33",
      "ipAddress": "199.215.226.46",
      "purposes": [
        "PORT_FORWARDING"
      ],
      "ports": [
        "22"
      ]
    }],
    "nics": [{
      "id": "f401d989-b149-4870-99f3-1991fec31454",
      "isDefault": true,
      "networkId": "d5a68379-a9ee-404f-9492-a1964b374d6f"
    }]
  }
}

GET /services/:service_code/:environment_name/instances/:id

Retrieve information about a specific instance.

Attributes
id UUID	The id of the instance
name string	The display name of the instance
affinityGroupIds Array[UUID]	The id(s) of the affinity groups to which the instance is associated.
computeOfferingId UUID	The compute offering id of the instance
computeOfferingName string	The compute offering name of the instance
cpuCount int	The number of vCPUs associated with the instance's compute offering
hostname string	The host name of the instance
imageId UUID	The image id of the instance
imageName string	The image name of the instance
ipAddress string	The instance's private IPv4 address
isPasswordEnabled boolean	Indicate whether a password can be used for remote connections
macAddress string	The instance's MAC address
memoryInMB int	The number of megabytes associated with the instance's compute offering
networkId UUID	The id of the network where instance is deployed
networkName string	The name of the network where instance is deployed
nics Array[NIC]	The NICs of the instance includes: id, isDefault, networkId
publicIps Array[PublicIp]	The public IP addresses associated to the instance includes: id, purposes, ipAddress, ports
state string	The current state of the instance
userData string	The user data of the instance
username string	The username that can be used to connect to the instance
vpcId UUID	The id of the associated VPC
vpcName string	The name of associated VPC
zoneId UUID	The id of the zone where instance is deployed
zoneName string	The name of associated zone

Create an instance

# Here is the absolute minimum information required to create a new instance:
curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances"

Request body example:

{
   "name": "jarvis",
   "additionalDiskIops": 1000,
   "additionalDiskSizeInGb": 20,
   "affinityGroupId": "1c0bfd2b-d609-4892-a43e-273654532d26",
   "computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
   "diskOfferingId": "f16f7f1b-462d-47b9-97bb-25a19e47a648",
   "networkId": "55ccea7f-8286-479e-a648-dd4a45866daf",
   "portsToForward": ["80", "9999"],
   "rootVolumeSizeInGb": 60,
   "sshKeyName": "mysshkey",
   "templateId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
   "userData": "#!/bin/bash\necho 'hello world'",
   "volumeIdToAttach": "2478012b-3cf3-4eef-a8d6-85eb8599df6d"
}

POST /services/:service_code/:environment_name/instances

Create an instance in an environment. This endpoint allows you to easily attach a new or existing data volume and add port forwarding rules to the new instance without doing additional API calls.

In order to create bare metal instances, please see the acquire operation.

Required
name string	Name of the newly created instance
computeOfferingId UUID	The compute offering will determine the number of CPU and RAM of your instance
networkId UUID	The network in which the instance will be created. If you don't have a network, it can be created through the create network api.
templateId UUID	The template to use for this instance

Optional
additionalDiskIops int	The number of IOPS the additional disk should have. You must choose a disk offering with custom IOPS enabled.
additionalDiskSizeInGb int	The number of GB the additional disk should have. You must choose a disk offering with custom disk size enabled.
affinityGroupId UUID	The affinity group where to create the instance.
cpuCount int	If the compute offering requires custom values (i.e. "custom": true), this value must be provided.
diskOfferingId UUID	The disk offering to be used for a new volume to attach to this instance
ipAddress string	Private IPv4 address of this instance, must be within network's CIDR and not collide with other instances on the network.
memoryInMB int	If the compute offering requires custom values (i.e. "custom": true), this value must be provided.
portsToForward array[string]	The ports you would like to open on the instance. It will try to use an existing public IP address, if it can't find one it will acquire a new public IP.
publicKey string	The public key to use for this instance.
rootVolumeSizeInGb int	The number of GB of the root volume. You must choose a template that allows the resize of root volume. If none specified, then the default one of the template will be used.
sshKeyName string	The name of the SSH key to use for this instance. If you don't have an SSH key registered, you can do so through this api.
userData string	User data is data that can be accessed and interpreted in the instance.
volumeIdToAttach UUID	The volume to attach to this instance.

Update an instance

# Here is the absolute minimum information required to create a new instance:
curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29"

Request body example:

{
   "name": "hal",
   "hostname": "hal_9000"
}

POST /services/:service_code/:environment_name/instances/:id

Update the name and hostname of an existing instance.

Optional
name string	Updated name of instance
hostname string	Updated hostname of instance.

Destroy an instance

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint:443/v1/services/compute-on/test_area/instances/5bf7352c-eed2-43dc-83f1-89917fb893ca" 

Request body example:

{
   "deleteSnapshots":true,
   "purgeImmediately":true,
   "publicIpIdsToRelease":[
      "fe446d61-a22c-403a-87bf-5351e65dc54d"
   ],
   "volumeIdsToDelete":[
      "e3d4045d-3ef7-464d-92a3-fc18269f36e2"
   ]
}

DELETE /services/:service_code/:environment_name/instances/:id

Destroys an existing instance. The instance needs to be in the Running, Stopped or Error state for the operation to work. This endpoint allows you to do additional cleanup of resources attached to this instance such as public IPs, volumes and snapshots. If the purgeImmediately flag is not true, then it will not completely remove the instance from the environment. (i.e. the instance could still be recovered).

In order to destory bare metal instances, please see the release operation.

Optional
deleteSnapshots boolean	Will delete all snapshots of volumes attached to this instance if true, will keep snapshots otherwise.
publicIpIdsToRelease Array[UUID]	List of IDs of the public IP addresses to release with the instance. Can only release public IPs of the instance being destroyed and they must not be used by other instances.
purgeImmediately boolean	Will destroy and purge the instance if true, puts the instance in destroyed state otherwise. An instance that wasn't purged can be recovered.
volumeIdsToDelete Array[UUID]	List of IDs of the data volumes to delete with the instance. Can only destroy data volumes that are attached to this instance.

Start an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=start"

POST /services/:service_code/:environment_name/instances/:id?operation=start

Start an existing instance. The instance must be in the Stopped state for this operation to work.

Stop an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=stop"

Request body example:

{
   "forceStop":true
}

POST /services/:service_code/:environment_name/instances/:id?operation=stop

Stop an existing instance. The instance must be in either the Running or Stopping state for this operation to work. The default behavior is that the instance (denote by id) will be stopped gracefully. An additional parameter can be passed with the call to force stop an instance. If the API is invoked on an instance that is already in the Stopping state, then a force stop is enforced regardless of whether this optional parameter was provided or not.

Optional
forceStop boolean	Setting it to true will force stop an instance that is either Running or in the process of Stopping

Reboot an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=reboot"

POST /services/:service_code/:environment_name/instances/:id?operation=reboot

Reboot an existing instance. The instance must be in the Running or Stopped state for this operation to work.

Purge an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=purge"

POST /services/:service_code/:environment_name/instances/:id?operation=purge

Purges an existing instance (i.e. completely remove it from the environment). The instance must be in a Destroyed state.

Recover an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=recover"

POST /services/:service_code/:environment_name/instances/:id?operation=recover

Recover an existing instance that was previously destroyed. The instance must be in a Destroyed state.

Change the compute offering of an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=changeComputeOffering"

POST /services/:service_code/:environment_name/instances/:id?operation=changeComputeOffering

Change the compute offering of an existing instance.

Required
computeOfferingId UUID	Id of the new compute offering for the instnace

Required	(if custom compute offering)
cpuCount integer	Number of CPUs for the instance
memoryInMB integer	Amount of memory in MB for the instance

Reset the password of an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=resetPassword"

POST /services/:service_code/:environment_name/instances/:id?operation=resetPassword

Reset the password of the default user of an existing instance. The new password of the instance will be in the task result.

Change network of an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=changeNetwork"

POST /services/:service_code/:environment_name/instances/:id?operation=changeNetwork

Move an instance to another network. NOTE: This will destroy all port forwarding rules associated to this instance and remove the instance from all load balancing rules. Additionally, it will reboot your instance.

Required
networkId UUID	The destination network.

Associate an SSH key to an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=associateSSHKey"

Request body example:

{
   "sshKeyName": "my_ssh_key"
}

POST /services/:service_code/:environment_name/instances/:id?operation=associateSSHKey

Associate a new SSH key to the default user of an existing instance. This will override any other SSH key associated to the instance for the default user. You can register a new SSH key with the register SSH key endpoint.

Required
sshKeyName string	The name of the SSH key to associate to the instance

Attach an ISO to an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=attachIso"

Request body example:

{
   "isoId": "f092a051-8b3f-4941-b47f-5ecb77f3423b"
}

POST /services/:service_code/:environment_name/instances/:id?operation=attachIso

Attach an existing, non-bootable ISO to an instance. Each instance may have only one ISO attached at a time.

Required
isoId UUID	The id of the ISO to attach

Detach the ISO from an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/instances/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=detachIso"

# No parameters required

POST /services/:service_code/:environment_name/instances/:id?operation=detachIso

Detach the currently attached ISO from an instance.

Bare metal instances

Deploy and manage your bare metal instances.

For information regarding virtual instances, please see instances.

List bare metal instances

Identical to virtual instances, please see list instances.

Retrieve a bare metal instance

Identical to virtual instances, please see retrieve an instance.

Acquire a bare metal instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances"

Request body example:

{
   "name": "jarvis",
   "computeOfferingId": "3caab5ed-b5a2-4d8a-82e4-51c46168ee6c",
   "networkId": "55ccea7f-8286-479e-a648-dd4a45866daf",
   "portsToForward": ["80", "9999"],
   "sshKeyName": "mysshkey",
   "templateId": "5f968ad6-56d0-4d0d-ad7e-f8f4a5b5d986",
   "userData": "#!/bin/bash\necho 'hello world'"
}

POST /services/:service_code/:environment_name/instances?operation=acquireBareMetal

Acquire a bare metal instance in an environment. This endpoint allows you to easily add port forwarding rules and user data to the instance without doing additional API calls. This operation is analogous to the create an instance operation for virtual instances.

Required
name string	Name of the newly created instance
computeOfferingId UUID	The compute offering will determine the hardware specifications of your instance.
networkId UUID	The network in which the instance will be created. If you don't have a network, it can be created through the create network api.
sshKeyName string	The name of the SSH key to use for this instance. If you don't have an SSH key registered, you can do so through this api.
templateId UUID	The template to use for this instance.

Optional
ipAddress string	Private IPv4 address of this instance, must be within network's CIDR and not collide with other instances on the network.
portsToForward array[string]	The ports you would like to open on the instance. It will try to use an existing public IP address, if it can't find one it will acquire a new public IP.
userData string	User data is data that can be accessed and interpreted in the instance.

Release a bare metal instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/instances/5951c2b8-e901-4c01-8ae0-cb8d7c508d29?operation=releaseBareMetal"

Request body example:

{
   "publicIpIdsToRelease":[
      "fe446d61-a22c-403a-87bf-5351e65dc54d"
   ]  
}

POST /services/:service_code/:environment_name/instances/:id?operation=releaseBareMetal

Release an acquired bare metal instance from the environment. The instance will be immediatedly released. This operation is analogous to the destroy an instance operation with the purgeImmediately flag set to true (i.e. the instance will not be recovered).

Associate an SSH key to an instance

Identical to virtual instances, please see associate an SSH key.

Templates

A template is a virtual disk image that can be used on the creation of an instance. It contains the operating system which can contain some predefined configuration, files and software.

List templates

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/templates"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
    "name": "ubuntu",
    "description": "Example template",
    "defaultUsername": "cmc-user",
    "size": 52428800,
    "availablePublicly": false,
    "ready": true,
    "dynamicallyScalable": true,
    "extractable": false,
    "sshKeyEnabled": true,
    "created":"2016-10-24 2:40:29 PM EDT",
    "zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
    "zoneName": "zone1",
    "osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
    "osTypeName": "Other (64-bit)",
    "availableInZones": [
       "ea901007-056b-4c50-bb3a-2dd635fce2ab"
    ],
    "hypervisor": "VMware",
    "format": "OVA",
    "nicAdapter": "e1000",
    "rootDiskController": "scsi",
    "keyboard": "uk"
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/templates

Retrieve a list of all templates of an environment It will include all the public templates of the system.

Attributes
id UUID	The id of the template
name string	The name of the template
description string	The description of the template
defaultUsername string	The default username of the template
size long	The size of the template in bytes
availablePublicly boolean	true if public to everyone. Your custom templates will always be private
ready boolean	true if the template is ready to be used for a new instance
dynamicallyScalable boolean	true if you can dynamically scale an instance with this template
extractable boolean	true if you want the template to be downloadable from a generated URL
created string	The creation date of the template
osTypeId UUID	Id of the OS type
osTypeName string	The OS type of the template (e.g. Ubuntu, CentOS...)
sshEnabled boolean	false if you want to enable sshKey for the template
zoneId UUID	The zone id that the template is available in. Empty if available in multiple zones
zoneName string	The zone id that the template is available in. Empty if available in multiple zones
availableInZones array[UUID]	List of all zone ids that the template is available in
hypervisor string	The name of the hypervisor
format string	The template format for the chosen hypervisor
nicAdapter string	VMWare only The network interface controller name. Empty if not selected. Values: e1000, pcnet32, vmxnet2 or vmxnet3.
rootDiskController string	VMWare only The root disk controller name. Empty if not selected. Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up.
keyboard string	VMWare only The keyboard type name. Empty if not selected. Values: us, uk, jp, sc.

Retrieve a template

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v1/services/compute-on/test_area/templates/162cdfcb-45e5-4aa6-81c4-124c94621bdb"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
    "name": "ubuntu",
    "description": "Example template",
    "defaultUsername": "cmc-user",
    "size": 52428800,
    "availablePublicly": false,
    "ready": true,
    "dynamicallyScalable": true,
    "extractable": false,
    "sshKeyEnabled": true,
    "created":"2016-10-24 2:40:29 PM EDT",
    "zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
    "zoneName": "zone1",
    "osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
    "osTypeName": "Other (64-bit)",
    "availableInZones": [
       "ea901007-056b-4c50-bb3a-2dd635fce2ab"
    ],
    "hypervisor": "VMware",
    "format": "OVA",
    "nicAdapter": "e1000",
    "rootDiskController": "scsi",
    "keyboard": "uk"
  }
}

GET /services/:service_code/:environment_name/templates/:id

Retrieve information about a public or private template of an environment.

Attributes
id UUID	The id of the template
name string	The name of the template
description string	The description of the template
defaultUsername string	The default username of the template
size long	The size of the template in bytes
availablePublicly boolean	true if public to everyone. Your custom templates will always be private
ready boolean	true if the template is ready to be used for a new instance
dynamicallyScalable boolean	true if you can dynamically scale an instance with this template
extractable boolean	true if you want the template to be downloadable from a generated URL
created string	The creation date of the template
osTypeId UUID	Id of the OS type
osTypeName string	The OS type of the template (e.g. Ubuntu, CentOS...)
sshEnabled boolean	false if you want to enable sshKey for the template
zoneId UUID	The zone id that the template is available in. Empty if available in multiple zones
zoneName string	The zone id that the template is available in. Empty if available in multiple zones
availableInZones array[UUID]	List of all zone ids that the template is available in
hypervisor string	The name of the hypervisor
format string	The template format for the chosen hypervisor
nicAdapter string	VMWare only The network interface controller name. Empty if not selected. Values: e1000, pcnet32, vmxnet2 or vmxnet3
rootDiskController string	VMWare only The root disk controller name. Empty if not selected. Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up
keyboard string	VMWare only The keyboard type name. Empty if not selected. Values: us, uk, jp, sc

Import a template

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/templates"

Request body example:

{
  "name": "debian",
  "description":"This is my template",
  "url":"http://somewhere.com/template-vmware.ova",
  "hypervisor":"VMWare",
  "format":"OVA",
  "keyboard":"us",
  "nicAdapter":"vmxnet3",
  "osTypeId": "53161a9c-6019-11e7-914a-0200246f00c5",
  "osTypeName": "Debian GNU/Linux 7(64-bit)",
  "zoneId":"e2cf7fa0-c3c2-4a39-9f8d-ee01ac3546cd"
}

POST /services/:service_code/:environment_name/templates

Import a template.

Required
name string	The name of the template
description string	The description of the template
url string	The URL where the template is hosted. Both http and https URLs are supported
zoneId UUID	The zone where it will be available. If there is only 1 zone, the field is optional
hypervisor string	The name of the hypervisor
format string	The template format for the chosen hypervisor
osTypeId UUID	Id of the OS type
osTypeName string	The OS type of the template (e.g. Ubuntu, CentOS...)

Optional
defaultUsername string	The default username of the template
size long	The size of the template in bytes
availablePublicly boolean	true if public to everyone. Your custom templates will always be private
dynamicallyScalable boolean	true if you can dynamically scale an instance with this template
extractable boolean	true if you want the template to be downloadable from a generated URL
nicAdapter string	VMWare only The network interface controller name. Empty if not selected. Values: e1000, pcnet32, vmxnet2 or vmxnet3
rootDiskController string	VMWare only The root disk controller name. Empty if not selected. Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up
keyboard string	VMWare only The keyboard type name. Empty if not selected. Values: us, uk, jp, sc
passwordEnabled boolean	false if want to set the reset password feature
sshEnabled boolean	false if you want to enable sshKey for the template

Update a template

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/templates/162cdfcb-45e5-4aa6-81c4-124c94621bdb?operation=update"

Request body example:

{
  "description":"This is my updated template description"
}

POST /services/:service_code/:environment_name/templates/:id/operation=update

Update a template.

Required
name string	The name of the template
description string	The description of the template

Optional
format string	The template format for the chosen hypervisor
osTypeId UUID	Id of the OS type
passwordEnabled boolean	false if want to set the reset password feature
sshEnabled boolean	false if you want to enable sshKey for the template
defaultUsername string	The default username of the template
dynamicallyScalable boolean	true if you can dynamically scale an instance with this template
nicAdapter string	VMWare only The network interface controller name. Empty if not selected. Values: e1000, pcnet32, vmxnet2 or vmxnet3
rootDiskController string	VMWare only The root disk controller name. Empty if not selected. Values: ide, scsi for CloudStack version up to 4.4. Values: ide, scsi, osdefault, pvscsi, lsilogic, lsisas1068, buslogic for CloudStack version 4.5 and up
keyboard string	VMWare only The keyboard type name. Empty if not selected. Values: us, uk, jp, sc

Delete a template

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v1/services/compute-on/test_area/templates/162cdfcb-45e5-4aa6-81c4-124c94621bdb"

DELETE /services/:service_code/:environment_name/templates/:id

Delete a private template.

ISOs

An ISO is a disk image that is a copy of a file system. A bootable ISO can be used to create an instance. Otherwise, an ISO may be attached to an existing instance.

List ISOs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/isos"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
    "name": "ubuntu",
    "description": "Example ISO",
    "architectureWidth": 64,
    "size": 52428800,
    "ready": true,
    "bootable": true,
    "availablePublicly": false,
    "extractable": false,
    "osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
    "osTypeName": "Other (64-bit)",
    "zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
    "zoneName": "zone1",
    "created": "2017-12-21 4:41:33 PM Z",
    "availableInZones": ["ea901007-056b-4c50-bb3a-2dd635fce2ab"]
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/isos

Retrieve a list of all ISOs of an environment.

Attributes
id UUID	The id of the ISO
name string	The name of the ISO
description string	The description of the ISO
architectureWidth string	Number of bits
size long	The size of the ISO in bytes
ready boolean	true if the ISO is ready to be used
bootable boolean	true if the ISO can be used for a new instance
osTypeId UUID	Id of th OS type
osTypeName string	The OS type of the ISO (e.g. Ubuntu, CentOS...)
zoneId UUID	The zone id that the ISO is available in. Empty if available in multiple zones
zoneName string	The zone id that the ISO is available in. Empty if available in multiple zones
created string	The date the template was created
availableInZones List[String]	The list of zone ids that the ISO is available in

Retrieve a ISO

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
"https://cloudmc_endpoint/api/v1/services/compute-on/test_area/isos/162cdfcb-45e5-4aa6-81c4-124c94621bdb"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "0b3fea04-b1ed-48cf-921d-96795dfe9a81",
    "name": "ubuntu",
    "description": "Example ISO",
    "architectureWidth": 64,
    "size": 52428800,
    "ready": true,
    "bootable": true,
    "availablePublicly": false,
    "extractable": false,
    "osTypeId":"d38dc1d9-dd34-4fdd-8f51-a973f8fe5f3b",
    "osTypeName": "Other (64-bit)",
    "zoneId":"ea901007-056b-4c50-bb3a-2dd635fce2ab",
    "zoneName": "zone1",
    "created": "2017-12-21 4:41:33 PM Z",
    "availableInZones": ["ea901007-056b-4c50-bb3a-2dd635fce2ab"]
  }
}

GET /services/:service_code/:environment_name/isos/:id

Retrieve information about a public or private ISO of an environment.

Attributes
id UUID	The id of the ISO
name string	The name of the ISO
description string	The description of the ISO
architectureWidth string	Number of bits
size long	The size of the ISO in bytes
ready boolean	true if the ISO is ready to be used
bootable boolean	true if the ISO can be used for a new instance
extractable boolean	true if the template allows download from a generated URL
osTypeId UUID	Id of th OS type
osTypeName string	The OS type of the ISO (e.g. Ubuntu, CentOS...)
zoneId UUID	The zone id that the ISO is available in. Empty if available in multiple zones
zoneName string	The zone id that the ISO is available in. Empty if available in multiple zones
created string	The date the template was created
availableInZones List[String]	The list of zone ids that the ISO is available in

Import ISO

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/isos"

Request body example:

{
   "name": "windows",
   "description":"This is my ISO",
   "url":"http://somewhere.com/somefile.iso",
   "zoneId":"d342520b-94aa-4e44-b066-6c18c9e4d65b"
}

POST /services/:service_code/:environment_name/isos

Import an ISO.

Required
name string	The name of the ISO
description string	The description of the ISO
url string	The URL where the ISO is hosted. N.B. only http protocol is supported
zoneId UUID	The zone where it will be available. If there is only 1 zone, the field is optional

Optional
bootable boolean	Indicates if the ISO is bootable or not. If provided, the osTypeId must be provided.
osTypeId UUID	The OS type of the image. Must only be provided if bootable is true.

Attach an ISO to an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/isos/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=attach"

Request body example:

{
   "instanceId": "c043e651-8b3f-4941-b47f-5ecb77f3423b"
}

POST /services/:service_code/:environment_name/isos/:id?operation=attach

Attach an existing, non-bootable ISO to an instance. Each instance may have only one ISO attached at a time.

Required
instanceId UUID	The id of the instance to which the ISO will be attached

Detach the ISO from an instance

See the Detach the ISO from an instance endpoint under Instances.

Generate a download URL for an ISO

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/isos/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=generateDownloadUrl"

# No parameters required

POST /services/:service_code/:environment_name/isos/:id?operation=generateDownloadUrl

Generate a URL that can be used to download an extractable ISO. The URL may also be used to import the ISO into another region. To be able to generate the download URL, the ISO must have been imported with the extractable flag set to true. The download URL will be placed in the url field of the task result.

Delete an ISO

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/isos/84fc07a8-c6a3-4538-b493-11ce69ea3c88"

DELETE /services/:service_code/:environment_name/isos/:id

Delete an ISO.

SSH keys

SSH keys can be assigned to default users of instances by using the associate SSH key operation.

List SSH keys

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sshkeys"

The above command returns a JSON structured like this:

{
  "data": [{
    "name": "mellon",
    "fingerprint": "91:8d:71:ca:2d:2c:ad:97:26:db:cb:c3:df:9a:e9:b6"
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/sshkeys

Retrieve a list of all SSH keys in an environment.

Attributes
name string	The name of the SSH key
fingerprint string	A short sequence of bytes used to identify the SSH key.

Retrieve an SSH key

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sshkeys/mellon"

The above command returns a JSON structured like this:

{
  "data": {
    "name": "mellon",
    "fingerprint": "91:8d:71:ca:2d:2c:ad:97:26:db:cb:c3:df:9a:e9:b6"
  }
}

GET /services/:service_code/:environment_name/sshkeys/:name

Retrieve information about an SSH key of an environment.

Attributes
name string	The name of the SSH key
fingerprint string	A short sequence of bytes used to identify the SSH key.

Affinity groups

Affinity groups are a way of influencing on which host an instance will be deployed. An anti-affinity group (the only type of affinity group we support) allows you to put instances on different hosts to increase fault-tolerance. In the unlikely event of a host failure, your services would still be up on another host (assuming you distribute your services on multiple instances).

List affinity groups

curl -X GET \
  -H "MC-Api-Key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/affinitygroups"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "d4fd794f-66e1-4906-a720-d0afb04bd517",
    "name": "gnr",
    "type":"host anti-affinity",
    "instanceIds": [
      "92b4df86-fee3-4610-8167-78332b86362f"
    ]
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/affinitygroups

Retrieve a list of all affinity groups in an environment.

Attributes
id UUID	The id of the affinity group
name string	The name of the affinity group
type string	The type of affinity group. We only support anti-affinity
instanceIds Array[UUID]	The ids of the instances in the affinity group

Retrieve an affinity group

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/affinitygroups/d4fd794f-66e1-4906-a720-d0afb04bd517"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "d4fd794f-66e1-4906-a720-d0afb04bd517",
    "name": "gnr",
    "type": "host anti-affinity",
    "instanceIds": [
      "92b4df86-fee3-4610-8167-78332b86362f"
    ]
  }
}

GET /services/:service_code/:environment_name/affinitygroups/:id

Retrieve information about an affinity group.

Attributes
id UUID	The id of the affinity group
name string	The name of the affinity group
type string	The type of affinity group. We only support anti-affinity
instanceIds Array[UUID]	The ids of the instances in the affinity group

Create an affinity group

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/affinitygroups"

Request body example:

{
   "name": "gnr",
   "description": "My affinity group",
   "type": "host anti-affinity",
   "instanceIds": [
     "92b4df86-fee3-4610-8167-78332b86362f"
   ]
}

POST /services/:service_code/:environment_name/affinitygroups

Create an affinity group and add instances to it.

Required
name string	The name of the new affinity group
description string	A description of the affinity group
type string	The type of new affinity group. We only support anti-affinity
instanceIds Array[UUID]	The ids of the instances in the affinity group

Update an affinity group

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/affinitygroups/d4fd794f-66e1-4906-a720-d0afb04bd517"

Request body example:

{
   "instanceIds": [
     "92b4df86-fee3-4610-8167-78332b86362f",
     "105f8b5e-5482-4bf5-88ca-7d7b7f431e3e"
   ]
}

PUT /services/:service_code/:environment_name/affinitygroups/:id

Update the list of instances in the affinity group.

Required
name string	The name of the new affinity group
description string	A description of the affinity group
type string	The type of new affinity group. We only support anti-affinity
instanceIds Array[UUID]	The ids of the instances in the affinity group

Delete an affinity group

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/affinitygroups/d4fd794f-66e1-4906-a720-d0afb04bd517"

DELETE /services/:service_code/:environment_name/affinitygroups/:id

Delete an existing affinity group.

Networking

VPCs

A Virtual Private Cloud (VPC) is a logically isolated section of CloudMC, where you can build a multi-network application architecture.

List VPCs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcs"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "9fe8e398-06d6-482c-8f55-b805bde4d3cc",
    "name": "MyVPC",
    "description": "Some VPC",
    "cidr": "10.155.24.0/22",
    "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
    "zoneName": "QC-1",
    "state": "Enabled",
    "networkDomain": "hello.world",
    "vpcOfferingId": "21a40b85-5fa9-440f-ab77-5e560073b584",
    "requiresUpgrade": false,
    "sourceNatIp": "172.31.3.253",
    "vpnStatus": "Disabled"
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/vpcs

Retrieve a list of all VPCs of an environment.

Attributes
id UUID	The id of the VPC
name string	The name of the VPC
description string	The description of the VPC
cidr string	The CIDR of a VPC
zoneId string	The id of the zone where the VPC was created
zoneName string	The name of the zone where the VPC was created
state string	The state of the VPC
networkDomain string	A custom DNS suffix at the level of a network
requiresUpgrade string	true if the VPC needs to be upgraded
sourceNatIp string	The source NAT IP of the VPC
vpnStatus string	The status of the VPN. The status can be ENABLED or DISABLED

Retrieve a VPC

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcs/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "9fe8e398-06d6-482c-8f55-b805bde4d3cc",
    "name": "MyVPC",
    "description": "Some VPC",
    "cidr": "10.155.24.0/22",
    "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
    "zoneName": "QC-1",
    "state": "Enabled",
    "networkDomain": "hello.world",
    "vpcOfferingId": "21a40b85-5fa9-440f-ab77-5e560073b584",
    "requiresUpgrade": false,
    "sourceNatIp": "172.31.3.253",
    "vpnStatus": "Disabled"
  }
}

GET /services/:service_code/:environment_name/vpcs/:id

Retrieve information about a VPC.

Attributes
id UUID	The id of the VPC
name string	The name of the VPC
description string	The description of the VPC
cidr string	The CIDR of a VPC
zoneId string	The id of the zone where the VPC was created
zoneName string	The name of the zone where the VPC was created
state string	The state of the VPC
networkDomain string	A custom DNS suffix at the level of a network
requiresUpgrade string	true if the VPC needs to be upgraded
sourceNatIp string	The source NAT IP of the VPC
vpnStatus string	The status of the VPN. The status can be ENABLED or DISABLED

Create a VPC

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcs"

Request body example:

{
  "name": "my_vpc",
  "description": "My prod VPC",
  "vpcOfferingId": "21a40b85-5fa9-440f-ab77-5e560073b584",
  "networkDomain": "hello.world"
}

POST /services/:service_code/:environment_name/vpcs

Create a VPC in an environment.

Required
name string	The name of the new VPC
description string	The description of the new VPC
vpcOfferingId UUID	The id of the VPC offering to use for the new VPC

Optional
networkDomain string	A custom DNS suffix at the level of a network

Update a VPC

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcs/d77e1ab1-0320-4504-83c5-e78b431c7577"

Request body example:

{
  "name": "my_updated_vpc",
  "description": "My prod VPC"
}

PUT /services/:service_code/:environment_name/vpcs

Update an existing VPC in your environment.

Optional
name string	The new name of the VPC
description string	The new description of the VPC

Destroy a VPC

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcs/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"

DELETE /services/:service_code/:environment_name/vpcs/:id

Destroy an existing VPC. To delete a VPC, you must first delete all the networks in the VPC.

Restart a VPC

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcs/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e?operation=restart"

POST /services/:service_code/:environment_name/vpcs/:id?operation=restart

Restart the router of a VPC.

Networks

A network is an isolated network with its own VLANs and CIDR list, where you can place groups of resources, such as instances. They can exist as VPC subnets, or as simple isolated networks, provided the appropriate network offerings exist.

List networks

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networks"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "8ef7539c-c9ba-49f3-a484-a08f4ffb2234",
    "name": "Frontend",
    "description": "default network",
    "vpcId": "12b8c150-b444-482a-8411-c08eaccb0a3b",
    "vpcName": "SomeVPC",
    "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
    "zoneName": "QC-1",
    "cidr": "10.169.254.0/24",
    "gateway": "10.169.254.1",
    "netmask": "255.255.255.0",
    "networkAclId": "9ba3ec65-2e1d-11e4-8e05-42a29a39fc92",
    "networkAclName": "default_allow",
    "networkOfferingId": "9593f0df-573a-43c4-a107-a5c704a7cfee",
    "networkOfferingName": "Load Balanced Network",
    "networkOfferingDescription": "Offering for Isolated Vpc networks with Source Nat service enabled",
    "state": "Implemented"
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/networks

Retrieve a list of all networks of an environment.

Attributes
id UUID	The id of the network
name string	The name of the network
description string	The description of the network
vpcId UUID	The id of the VPC where the network was created
vpcName string	The name of the VPC where the network was created
zoneId string	The id of the zone where the network was created
zoneName string	The name of the zone where the network was created
cidr string	The cidr of the network
gateway string	The gateway of the network
netmask string	The netmask of the network
networkAclId UUID	The id of the network ACL of the network
networkAclName string	The name of the network ACL of the network
networkOfferingId UUID	The id of the network offering of the network
networkOfferingName string	The name of the network offering of the network
networkOfferingDescription string	The description of the network offering of the network
state string	The state of the network. Allocated if no instances where created in the network yet, Implemented otherwise.

Query Parameters
vpc_id UUID	Filter the list to only retrieve the networks of a VPC
zone_id UUID	Filter the list to only retrieve the networks in a specific zone

Retrieve a network

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networks/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "8ef7539c-c9ba-49f3-a484-a08f4ffb2234",
    "name": "Frontend",
    "description": "default network",
    "vpcId": "12b8c150-b444-482a-8411-c08eaccb0a3b",
    "vpcName": "SomeVPC",
    "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
    "zoneName": "QC-1",
    "cidr": "10.169.254.0/24",
    "gateway": "10.169.254.1",
    "netmask": "255.255.255.0",
    "networkAclId": "9ba3ec65-2e1d-11e4-8e05-42a29a39fc92",
    "networkAclName": "default_allow",
    "networkOfferingId": "9593f0df-573a-43c4-a107-a5c704a7cfee",
    "networkOfferingName": "Load Balanced Network",
    "networkOfferingDescription": "Offering for Isolated Vpc networks with Source Nat service enabled",
    "state": "Implemented"
  }
}

GET /services/:service_code/:environment_name/networks/:id

Retrieve information about a network.

Attributes
id UUID	The id of the network
name string	The name of the network
description string	The description of the network
vpcId UUID	The id of the VPC where the network was created
vpcName string	The name of the VPC where the network was created
zoneId string	The id of the zone where the network was created
zoneName string	The name of the zone where the network was created
cidr string	The cidr of the network
gateway string	The gateway of the network
netmask string	The netmask of the network
networkAclId UUID	The id of the network ACL of the network
networkAclName string	The name of the network ACL of the network
networkOfferingId UUID	The id of the network offering of the network
networkOfferingName string	The name of the network offering of the network
networkOfferingDescription string	The description of the network offering of the network
state string	The state of the network. Allocated if no instances where created in the network yet, Implemented otherwise.

Create a network

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networks"

Request body example:

{
  "name": "my_network",
  "description": "My production network",
  "vpcId": "b1932c7c-0b85-450f-92b9-bfdeb3e80804",
  "networkOfferingId": "c5d4ffcd-56e2-407a-8b4d-06082b7365c4",
  "networkAclId": "9ba3ec65-2e1d-11e4-8e05-42a29a39fc92"
}

POST /services/:service_code/:environment_name/networks

Create a network in an environment.

If the network offering is a VPC subnet offering (indicated by the vpcOnly flag on the offering), the vpcId and networkAclId are required fields.

Required
name string	The name of the new network
description string	The description of the new network
networkOfferingId UUID	The id of the network offering to use for the network

Required (if VPC subnet)
vpcId UUID	The id of the VPC where to create the network
networkAclId UUID	The id of the network ACL to use for the network

For isolated networks
netmask string	The netmask to use for this network. e.g. 255.255.255.0
gateway string	The network's gateway. e.g. 10.0.0.1

Update a network

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networks/9572d2ea-a60d-478a-a75e-8ed31f2641f1"

Request body example:

{
  "name": "my_updated_network",
  "description": "My updated production network"
}

POST /services/:service_code/:environment_name/networks/:id

Update an existing network in an environment.

Required
name string	The updated name of the network
description string	The updated description of the network

Delete a network

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networks/9572d2ea-a60d-478a-a75e-8ed31f2641f1"

DELETE /services/:service_code/:environment_name/networks/:id

Delete an existing network in an environment To delete a network, you must first delete all the instances in the network.

Replace the network ACL

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networks/9572d2ea-a60d-478a-a75e-8ed31f2641f1?operation=replace"

Request body example:

{
  "name": "my_updated_network",
  "description": "My updated production network"
}

POST /services/:service_code/:environment_name/networks/:id?operation=replace

Replace the network ACL for a VPC subnet.

Required
networkAclId string	The id of the network ACL to use for the network

Network ACLs

Manage access control lists and their rules. To apply an ACL to a VPC subnet, replace the ACL of a network.

List network ACLs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkacls?vpc_id=eb763d03-9935-4cd4-8a42-99134e242ccb"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "736d0c2e-d6b5-43fc-bcf0-732fce9a509e",
      "vpcId": "eb763d03-9935-4cd4-8a42-99134e242ccb",
      "name": "custom-1",
      "description": "Allows network egress"
    },
    {
      "id": "3246de94-e7e7-11e3-9187-06669c0000ad",
      "name": "default_allow",
      "description": "Default Network ACL Allow All"
    },
    {
      "id": "32467792-e7e7-11e3-9187-06669c0000ad",
      "name": "default_deny",
      "description": "Default Network ACL Deny All"
    }
  ],
  "metadata": {
    "recordCount": 3
  }
}

GET /services/:service_code/:environment_name/networkacls?vpc_id=:vpc_id

Retrieve a list of network ACLs in a VPC.

Attributes
id UUID	The id of the network ACL
name string	The name of the network ACL
description string	The description of the network ACL
vpcId UUID	The VPC where this rule is available. Not present on default_allow and default_deny ACLs

Query Parameters
vpc_id UUID	Filter the list to only retrieve the network ACLs of a specific VPC

Retrieve a network ACL

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkacls/736d0c2e-d6b5-43fc-bcf0-732fce9a509e"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "736d0c2e-d6b5-43fc-bcf0-732fce9a509e",
    "vpcId": "eb763d03-9935-4cd4-8a42-99134e242ccb",
    "name": "custom-1",
    "description": "Allows network egress"
  }
}

GET /services/:service_code/:environment_name/networkacls/:id

Retrieve a specific network ACL by its id.

Attributes
id UUID	The id of the network ACL
name string	The name of the network ACL
description string	The description of the network ACL
vpcId UUID	The VPC where this rule is available. Not present on default_allow and default_deny ACLs

Create network ACL

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkacls"

POST /services/:service_code/:environment_name/networkacls

Create a new network ACL associated to a VPC.

Required
name string	The name of the network ACL
description string	The description of the network ACL
vpcId UUID	Networks of this VPC will be able to use the new ACL

Delete a network ACL

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkacls/736d0c2e-d6b5-43fc-bcf0-732fce9a509e"

DELETE /services/:service_code/:environment_name/networkacls/:id

Delete an ACL and all of its rules.

List a network ACL's rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkaclrules?network_acl_id=3246de94-e7e7-11e3-9187-06669c0000ad"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "3247167a-e7e7-11e3-9187-06669c0000ad",
      "networkAclId": "3246de94-e7e7-11e3-9187-06669c0000ad",
      "ruleNumber": "2",
      "description":"Allow all egress",
      "cidr": "0.0.0.0/0",
      "action": "Allow",
      "protocol": "ALL",
      "trafficType": "Egress",
      "state": "Active"
    },
    {
      "id": "3246fdb6-e7e7-11e3-9187-06669c0000ad",
      "networkAclId": "3246de94-e7e7-11e3-9187-06669c0000ad",
      "ruleNumber": "1",
      "description":"Allow all ingress",
      "cidr": "0.0.0.0/0",
      "action": "Allow",
      "protocol": "ALL",
      "trafficType": "Ingress",
      "state": "Active"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/networkaclrules?network_acl_id=:network_acl_id

List a network ACL's rules.

Attributes
id UUID	The id of the network ACL rule
networkAclId UUID	The id of the network ACL that this rule belongs to
ruleNumber int	The relative position of this rule in its ACL
cidr CIDR	The network addresses targeted by this rule
action string	What to do with traffic matched by this rule. Either Allow or Deny
protocol string	The protocols targeted by this rule. TCP, UDP, ICMP, or ALL
trafficType string	The direction of traffic targeted by this rule. Either Ingress or Egress
state string	The state of this rule. Either Active or Inactive
description string	The description of the rule

Query Parameters
network_acl_id UUID	Filter the list to only retrieve the rules of a specific network ACL

Retrieve a network ACL rule

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkaclrules/3247167a-e7e7-11e3-9187-06669c0000ad"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "3247167a-e7e7-11e3-9187-06669c0000ad",
    "networkAclId": "3246de94-e7e7-11e3-9187-06669c0000ad",
    "ruleNumber": "2",
    "description":"Allow all egress",
    "cidr": "0.0.0.0/0",
    "action": "Allow",
    "protocol": "ALL",
    "trafficType": "Egress",
    "state": "Active"
  }
}

GET /services/:service_code/:environment_name/networkaclrules/:id

Attributes
id UUID	The id of the network ACL rule
networkAclId UUID	The id of the network ACL that this rule belongs to
ruleNumber int	The relative position of this rule in its ACL
cidr CIDR	The network addresses targeted by this rule
action string	What to do with traffic matched by this rule. Either Allow or Deny
protocol string	The protocols targeted by this rule. TCP, UDP, ICMP, or ALL
trafficType string	The direction of traffic targeted by this rule. Either Ingress or Egress
state string	The state of this rule. Either Active or Inactive
description string	The description of the rule

Create a network ACL rule

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkaclrules"

POST /services/:service_code/:environment_name/networkaclrules

Required
networkAclId UUID	The id of the network ACL to add this rule to
ruleNumber int	The relative position of this rule in its ACL
cidr CIDR	The network addresses targeted by this rule
action string	What to do with traffic matched by this rule. Either Allow or Deny
protocol string	The protocols targeted by this rule. TCP, UDP, ICMP, or ALL
trafficType string	The direction of traffic targeted by this rule. Either Ingress or Egress

Protocol-specific
startPort int	The start of the port range targeted by this rule. Required if the protocol is TCP or UDP
endPort int	The end of the port range targeted by this rule. Required if the protocol is TCP or UDP
icmpType int	ICMP message type. Required if the protocol is ICMP
icmpCode int	ICMP message error code. Required if the protocol is ICMP

Optional
description string	The description of the rule

Update a network ACL rule

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkaclrules/3247167a-e7e7-11e3-9187-06669c0000ad"

PUT /services/:service_code/:environment_name/networkaclrules/:id

Update a network ACL rule.

Optional
ruleNumber int	The relative position of this rule in its ACL
cidr CIDR	The network addresses targeted by this rule
description string	The description of the rule
action string	What to do with traffic matched by this rule. Either Allow or Deny
protocol string	The protocols targeted by this rule. TCP, UDP, ICMP, or ALL
trafficType string	The direction of traffic targeted by this rule. Either Ingress or Egress
startPort int	The start of the port range targeted by this rule
endPort int	The end of the port range targeted by this rule
icmpType int	ICMP message type
icmpCode int	ICMP message error code

Delete a network ACL rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkaclrules/3247167a-e7e7-11e3-9187-06669c0000ad"

DELETE /services/:service_code/:environment_name/networkaclrules/:id

Delete a specific rule of a network ACL.

Public IPs

List public IPs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/publicipaddresses"

The above command returns a JSON structured like this:

{
   "data": [
      {
         "id": "0ed72307-e33d-4d41-90b7-7d2b4f0d1ae0",
         "instances": [
            {
               "id": "986cfea3-4a94-407d-b915-eb2d49e4323f",
               "name": "i-pdube-F49"
            }
         ],
         "ipAddress": "69.196.164.98",
         "networkId": "def89cb6-f897-435a-ad7f-6b2d05ab11e6",
         "networkName": "web",
         "purposes": [
            "PORT_FORWARDING"
         ],
         "state": "Allocated",
         "vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb",
         "vpcName": "secondary",
         "zoneId": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
         "zoneName": "ON-1"
      },
      {
         "id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
         "ipAddress": "208.80.152.201",
         "purposes": [
            "SOURCE_NAT"
         ],
         "state": "Allocated",
         "vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb",
         "vpcName": "primary",
         "zoneId": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
         "zoneName": "ON-1"
      }
   ],
   "metadata": {
      "recordCount": 2
   }
}

GET /services/:service_code/:environment_name/publicipaddresses

List allocated public IP addresses.

Attributes
id UUID	The id of the public IP
instances Array[Instance]	The associated instances includes: id,name
ipAddress string	The IP address (e.g. 208.80.154.224)
networkId UUID	The associated network id
networkName string	The associated network name
purposes Array[string]	The list of purposes of the IP address. Possible values: STATIC_NAT, PORT_FORWARDING, LOAD_BALANCING, SOURCE_NAT or SOURCE_NAT and VPN
state string	The state of the public IP
vpcId UUID	The id of the VPC
vpcName string	The name of the VPC
zoneId UUID	The id of the zone
zoneName string	The name of the zone

Query Parameters
vpc_id UUID	Filter the list to only retrieve the public IPs in a specific VPC
instance_id UUID	Filter the list to only retrieve the public IPs associated to a specific instance

Retrieve a public IP

curl -X GET -H "MC-Api-Key: your_api_key"
"https://cloudmc_endpoint/api/v1/services/compute-on/test_area/publicipaddresses/10001e7d-b4ef-489b-836e-0619a383bc8d"

The above command returns a JSON structured like this:

{
   "data": {
      "id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
      "ipAddress": "208.80.152.201",
      "purposes": [
          "SOURCE_NAT"
      ],
      "state": "Allocated",
      "vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb",
      "vpcName": "primary",
      "zoneId": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
      "zoneName": "ON-1"
   }
}

GET /services/:service_code/:environment_name/publicipaddresses/:id

Retrieve a public IP address.

Attributes
id UUID	The id of the public IP
instances Array[Instance]	The associated instances includes: id,name
ipAddress string	The IP address (e.g. 208.80.154.224)
networkId UUID	The associated network id
networkName string	The associated network name
purposes Array[string]	The list of purposes of the IP address. Possible values: STATIC_NAT, PORT_FORWARDING, LOAD_BALANCING, SOURCE_NAT or SOURCE_NAT and VPN
state string	The state of the public IP
vpcId UUID	The id of the VPC
vpcName string	The name of the VPC
zoneId UUID	The id of the zone
zoneName string	The name of the zone

Acquire a public IP

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/publicipaddresses"

Request body example:

{
   "vpcId": "0687f5ce-89f9-47c8-9f58-c522455d56eb"
}

POST /services/:service_code/:environment_name/publicipaddresses

Acquire a public IP address for a VPC.

Required
vpcId UUID	The id of the VPC where to acquire the public IP

Release a public IP

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/publicipaddresses/a723b2b1-e343-4ea1-afe0-bf345a99a92b"

DELETE /services/:service_code/:environment_name/publicipaddresses/:id

Release a public IP. When acquiring a public IP, you are not guaranteed to receive a previously owned public IP, so be careful when releasing public IPs.

Enable static NAT

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -H "Content-Type: application/json" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/publicipaddresses/a723b2b1-e343-4ea1-afe0-bf345a99a92b?operation=enableStaticNat"

Request body example:

{
   "privateIpId": "5e30609d-7098-4d93-8317-3ecfe316ed00"
}

POST /services/:service_code/:environment_name/publicipaddresses/:id?operation=enableStaticNat

Enable static NAT on a public IP address.

Required
privateIpId string	The private IP id of the instance which is to be available on that IP. It can also be done on a secondary IP id.

Disable static NAT

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/publicipaddresses/a723b2b1-e343-4ea1-afe0-bf345a99a92b?operation=disableStaticNat"

POST /services/:service_code/:environment_name/publicipaddresses/:id?operation=disableStaticNat

Disable static NAT on that public IP.

Port forwarding rules

Port forwarding allows traffic from external hosts to services offered by applications in your VPCs. A port forwarding rule is a mapping of public IP ports to private IP ports (i.e. forwards traffic from a public IP to an instance).

List port forwarding rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/portforwardingrules"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "bf145d1e-7beb-42b8-bd2c-1a316aeb9aef",
    "ipAddress": "74.121.244.23",
    "ipAddressId": "747e30d0-a0cd-48ba-b7d8-77a2f7e10504",
    "privatePortStart": "8080",
    "privatePortEnd": "8080",
    "publicPortStart": "80",
    "publicPortEnd": "80",
    "protocol": "TCP",
    "instanceId": "d7328dd9-882e-4d08-8ad2-c74c2d493689",
    "instanceName": "my_app_instance",
    "networkId": "7388f551-4163-4467-b49b-58e9310d7207",
    "vpcId": "39907f0a-c253-42b8-b02d-337e00e9851e",
    "privateIp": "10.155.24.145",
    "privateIpId": "10.155.24.145   "
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/portforwardingrules

Retrieve a list of all port forwarding rules of an environment.

Attributes
id UUID	The id of the port forwarding rule
ipAddress string	The ip address of the public IP associated to this port forwarding rule
ipAddressId UUID	The id of the public IP associated to this port forwarding rule
privatePortStart string	The start of the private port range
privatePortEnd string	The end of the private port range
publicPortStart string	The start of the public port range
publicPortEnd string	The end of the public port range
protocol string	The protocol of the port forwarding rule (e.g. TCP, UDP)
instanceId UUID	The id of the instance of the port forwarding rule
instanceName string	The name of the instance of the port forwarding rule
networkId UUID	The id of the network of the port forwarding rule
vpcId UUID	The id of the VPC of the port forwarding rule
privateIp string	The private IP address of the instance where the traffic will be forwarded
privateIpId UUID	The id of private IP address of the instance where traffic will be forwarded

Query Parameters
instance_id UUID	Filter the list to only retrieve the port forwarding rules of an instance

Retrieve a port forwarding rule

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/portforwardingrules/ad5bcae8-ee8b-4ee8-a7a4-381c25444b8e"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "bf145d1e-7beb-42b8-bd2c-1a316aeb9aef",
    "ipAddress": "74.121.244.23",
    "ipAddressId": "747e30d0-a0cd-48ba-b7d8-77a2f7e10504",
    "privatePortStart": "8080",
    "privatePortEnd": "8080",
    "publicPortStart": "80",
    "publicPortEnd": "80",
    "protocol": "TCP",
    "instanceName": "my_app_instance",
    "instanceId": "d7328dd9-882e-4d08-8ad2-c74c2d493689",
    "networkId": "7388f551-4163-4467-b49b-58e9310d7207",
    "vpcId": "39907f0a-c253-42b8-b02d-337e00e9851e",
    "privateIp": "10.155.24.145",
    "privateIpId": "fc9d60a5-a8f8-4d01-a63f-f1731440063f"
  }
}

GET /services/:service_code/:environment_name/portforwardingrules/:id

Retrieve information about a port forwarding rule.

Attributes
id UUID	The id of the port forwarding rule
ipAddress string	The ip address of the public IP associated to this port forwarding rule
ipAddressId UUID	The id of the public IP associated to this port forwarding rule
privatePortStart string	The start of the private port range
privatePortEnd string	The end of the private port range
publicPortStart string	The start of the public port range
publicPortEnd string	The end of the public port range
protocol string	The protocol of the port forwarding rule (e.g. TCP, UDP)
instanceId UUID	The id of the instance of the port forwarding rule
instanceName string	The name of the instance of the port forwarding rule
networkId UUID	The id of the network of the port forwarding rule
vpcId UUID	The id of the VPC of the port forwarding rule
privateIp string	The private IP address of the instance where requests will be forwarded
privateIpId UUID	The id of private IP address of the instance where requests will be forwarded

Create a port forwarding rule

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/portforwardingrules"

Request body example:

{
  "ipAddressId": "4daf6ce5-a8b1-47d2-96b3-8edda63d891c",
  "instanceId": "0ec9ee23-f9dd-4830-acb6-7f8d4469673a",
  "protocol": "TCP",
  "privatePortStart": "8080",
  "privatePortEnd": "8080",
  "publicPortStart": "80",
  "publicPortEnd": "80"
}

POST /services/:service_code/:environment_name/portforwardingrules

Create a port forwarding rule for a public IP.

Required
ipAddressId UUID	The id of the public IP where the port forwarding should be created
protocol string	The protocol (e.g. TCP, UDP) to forward
privatePortStart string	The start of the private port range
privatePortEnd string	The end of the private port range
publicPortStart string	The start of the public port range
publicPortEnd string	The end of the public port range

Optional
instanceId UUID	The id of the instance that will have a port forwarded (it will use the default private port)
privateIpId UUID	The id of the private IP to forward

Delete a port forwarding rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/portforwardingrules/7d22b390-cbb3-4df6-96c6-52901ccb63c0"

DELETE /services/:service_code/:environment_name/portforwardingrules/:id

Delete an existing port forwarding rule.

Load balancer rules

List load balancer rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/loadbalancerrules?public_ip_id=eb763d03-9935-4cd4-8a42-99134e242ccb"

The above command returns a JSON structured like this:

{
  "data": [
     {
        "id": "32804ef2-dea6-4b07-b507-b3562bb9844a",
        "name": "web_lbr",
        "networkId": "394873ef-8655-49b6-8096-58b99c4e2347",
        "publicIp": "172.31.3.202",
        "publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
        "publicPort": "80",
        "privatePort": "80",
        "algorithm": "roundrobin",
        "protocol": "ssl",
        "stickinessMethod": "AppCookie",
        "instanceIds": [
           "d7048640-35d4-4a4f-8193-f4837da7e861"
        ],
        "sslCertificateId": "b1bea50a-e5f0-4b1e-bc0d-1dde909ac49a",
        "stickinessPolicyId": "217c1140-4146-4af0-92e9-ad47d4ff5ba9",
        "stickinessPolicyParameters": {
           "mode": "test",
           "indirect": "false",
           "domain": "some_domain",
           "postonly": "false",
           "nocache": "true",
           "cookieName": "test"
        }
     }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/loadbalancerrules?public_ip_id=:public_ip_id

Retrieve a list of load balancer rules.

Attributes
id UUID	The id of the load balancer rule
name string	The name of the load balancer rule
networkId string	The network id of the load balancer rule
publicIp UUID	The public IP of this load balancer rule
publicIpId string	The id of the public IP of this load balancer rule
publicPort int	The public port of this load balancer rule
privatePort int	The private port of this load balancer rule
algorithm string	The algorithm to use for this load balancer rule
protocol string	The protocol to load balance
stickinessMethod string	The stickiness policy of the load balancer rule
stickinessPolicyParameters Map[string,string]	The stickiness policy parameters of the load balancer rule
instanceIds Array[string]	The ids of the instances being load balanced

Query Parameters
public_ip_id UUID	Filter the list to only retrieve the load balancer rules of a public IP

Retrieve a load balancer rule

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/loadbalancerrules/f8ed7f44-449c-4510-848c-dc18e6665db1"

The above command returns a JSON structured like this:

{
  "data": {
      "id": "f8ed7f44-449c-4510-848c-dc18e6665db1",
      "name": "web_lbr",
      "networkId": "394873ef-8655-49b6-8096-58b99c4e2347",
      "publicIp": "172.31.3.202",
      "publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
      "publicPort": "22",
      "privatePort": "22",
      "algorithm": "roundrobin",
      "protocol": "tcp",
      "stickinessMethod": "LbCookie",
      "instanceIds": [
         "056cbb23-9021-4df7-b458-721ed9153ba9"
      ],
      "stickinessPolicyId": "29a1946c-5b59-4ab1-b9b8-5c73444b1c10",
      "stickinessPolicyParameters": {
         "mode": "test",
         "indirect": "false",
         "domain": "some_domain",
         "postonly": "false",
         "nocache": "true",
         "cookieName": "test"
      }
   }
}

GET /services/:service_code/:environment_name/loadbalancerrules/:id

Retrieve a specific load balancer rule by its id.

Attributes
id UUID	The id of the load balancer rule
name string	The name of the load balancer rule
networkId string	The network id of the load balancer rule
publicIp UUID	The public IP of this load balancer rule
publicIpId string	The id of the public IP of this load balancer rule
publicPort int	The public port of this load balancer rule
privatePort int	The private port of this load balancer rule
algorithm string	The algorithm to use for this load balancer rule
protocol string	The protocol to load balance
stickinessMethod string	The stickiness policy of the load balancer rule
stickinessPolicyParameters Map[string,string]	The stickiness policy parameters of the load balancer rule
instanceIds Array[string]	The ids of the instances being load balanced

Create a load balancer rule

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/loadbalancerrules"

Request body example:

{
   "name": "test",
   "publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
   "networkId": "093f6208-8a56-4035-8e71-3e39029fc5aa",
   "publicPort": "80",
   "privatePort": "80",
   "algorithm": "roundrobin",
   "protocol": "ssl",
   "stickinessMethod": "AppCookie",
   "instanceIds": [
      "d7048640-35d4-4a4f-8193-f4837da7e861"
   ],
   "sslCertificateId": "b1bea50a-e5f0-4b1e-bc0d-1dde909ac49a",
   "stickinessPolicyParameters": {
      "holdtime": 3600000
   }
}

POST /services/:service_code/:environment_name/loadbalancerrules

Create a new load balancer rule associated to a public IP.

Required
name string	The name of the load balancer rule
publicIpId string	The id of the public IP of this load balancer rule
publicPort int	The public port of this load balancer rule
privatePort int	The private port of this load balancer rule
algorithm string	The algorithm to use for this load balancer rule (roundrobin, leastconn or source)
protocol string	The protocol to load balance (TCP, UDP or TCP-PROXY)

Optional (required if public IP already assigned a network)
networkId string	The network id of the load balancer rule

Optional
stickinessMethod string	The stickiness policy of the load balancer rule
stickinessPolicyParameters Map[string, object]	The stickiness policy parameters of the load balancer rule
instanceIds Array[string]	The ids of the instances being load balanced
sslCertificateId UUID	The id of the SSL certificate for the load balancer rule. Can only be used with SSL protocol.

LbCookie parameters
cookieName string	Name of the cookie to be inserted by the load balancer for load balancing
mode string	rewrite, insert or prefix. rewrite: This keyword indicates that the cookie will be provided by the server and that the load balancer will have to modify its value to set the server's identifier in it. insert: This keyword indicates that the persistence cookie will have to be inserted by the load balancer in server responses if the client did not already have a cookie that would have permitted it to access this server. prefix: This keyword indicates that instead of relying on a dedicated cookie for the persistence, an existing one will be completed.
nocache boolean	This option is recommended in conjunction with the insert mode when there is a cache between the client and the load balancer, as it ensures that a cacheable response will be tagged non-cacheable if a cookie needs to be inserted.
indirect boolean	When this option is specified, no cookie will be emitted to a client which already has a valid one for the server which has processed the request.
postonly boolean	This option ensures that cookie insertion will only be performed on responses to POST requests.
domain string	This option allows to specify the domain at which a cookie is inserted.

AppCookie parameters
cookieName string	Name of the cookie to be inserted by the application for load balancing.
mode string	This option allows to change the URL parser mode. path-parameters(default) will look for the appsession cookie in the path parameters. query-parameters will look for the appsession cookie in the query parameters.
length string	The maximum number of characters to check in the cookie value.
holdtime boolean	Time in milliseconds that the cookie should be saved.
requestLearn boolean	If true, then it will be able to learn the cookie found in the request in case the server does not specify any in response.
prefix string	If true, then it will match on the cookie prefix (or URL parameter prefix). The appsession value is the data following this prefix.

SourceBased parameters
tableSize string	The maximum number of entries that can be stored in the table.
expires string	Defines the maximum duration of an entry in the table since it was last created, refreshed or matched. The expiration delay is defined using the standard time format, similarly as the various timeouts.

For more information, please consult section 4.2 of the HAProxy configuration manual. (AppCookie, LbCookie, SourceBased)

Update a load balancer rule

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/loadbalancerrules/3247167a-e7e7-11e3-9187-06669c0000ad"

Request body example:

{
   "name": "test",
   "algorithm": "roundrobin"
}

PUT /services/:service_code/:environment_name/loadbalancerrules/:id

Update a load balancer rule.

Optional
name string	The name of the load balancer rule
algorithm string	The algorithm of the load balancer rule (roundrobin, leastconn or source)

Update instances of a load balancer rule

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/loadbalancerrules/3247167a-e7e7-11e3-9187-06669c0000ad"

Request body example:

{
   "instanceIds": [
      "95d034b5-b902-440c-b430-120efaed9caf", "60df0bc2-f59b-4608-8147-1b8ac4a39add"
   ]
}

PUT /services/:service_code/:environment_name/loadbalancerrules/:id?operation=updateInstances

Update instances of a load balancer rule.

Required
instanceIds Array[String]	The instances of the load balancer rule

Update stickiness policy of a load balancer rule

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/loadbalancerrules/3247167a-e7e7-11e3-9187-06669c0000ad"

Request body example:

{
   "stickinessMethod": "LbCookie",
   "stickinessPolicyParameters": {
      "mode": "test",
      "indirect": "false",
      "domain": "some_domain",
      "postonly": "false",
      "nocache": "true",
      "cookieName": "test"
   }
}

PUT /services/:service_code/:environment_name/loadbalancerrules/:id?operation=updateStickiness

Update instances of a load balancer rule.

Required
stickinessMethod string	The stickiness policy for the load balancer rule
stickinessPolicyParameters Map[String, String]	The parameters for the stickiness policy of the load balancer rule

See Create a load balance rule for stickiness policy parameters documentation.

Delete a load balancer rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/loadbalancerrules/736d0c2e-d6b5-43fc-bcf0-732fce9a509e"

DELETE /services/:service_code/:environment_name/loadbalancerrules/:id

Delete a load balancer rule.

Ingress rules

Manage inbound traffic rules for isolated networks.

List ingress rules

curl -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/ingressrules"

The above command returns a JSON structured like this:

{
    "data": [
       {
            "id": "f6c7f86f-1e28-42fd-804f-0416a201a778",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "publicIp": "172.31.3.202",
            "publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
            "sourceCidr": "10.2.1.0/25",
            "protocol": "TCP",
            "startPort": "80",
            "endPort": "90",
            "state": "Active"
        },
        {
            "id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "publicIp": "172.31.3.202",
            "publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
            "sourceCidr": "10.2.1.0/24",
            "protocol": "UDP",
            "startPort": "",
            "endPort": "",
            "state": "Active"
        },
        {
            "id": "d860f2e7-ad15-4cb0-8477-6aa439245d1f",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "publicIp": "172.31.3.202",
            "publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
            "sourceCidr": "10.2.1.0/24",
            "protocol": "ICMP",
            "icmpType": "3",
            "icmpCode": "5",
            "state": "Active"
        }
    ],
    "metadata": {
        "recordCount": 3
    }
}

GET /services/:service_code/:environment_name/ingressrules

List ingress rules.

Attributes
id UUID	The id of the ingress rule
networkId string	The id of the isolated network the rule applies to
publicIp string	The public IP of this ingress rule
publicIpId UUID	The id of the public IP of this ingress rule
sourceCidr string	The source cidr
protocol string	The protocol the rule applies to. Possible values: TCP, UDP, ICMP
startPort string	The start port (for TCP/UDP protocols only). Can be empty for all ports.
endPort string	The end port (for TCP/UDP protocols only). Can be empty to match the start port value.
icmpType string	The ICMP type (for ICMP protocol only)
icmpCode string	The ICMP code (for ICMP protocol only)
state string	The state. Possible values: Active, Inactive

Query Parameters
network_id UUID	Filter the list to only retrieve the ingress rules of a specific Network
public_ip_id UUID	Filter the list to only retrieve the ingress rules of a specific public IP

Retrieve a specific ingress rule

curl -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/ingressrules/f1863d10-e7ec-4f17-8cdd-0e4046643b0b"

The above command returns a JSON structured like this:

{
    "data": {
            "id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "publicIp": "172.31.3.202",
            "publicIpId": "44ebac5d-18cc-4eea-ab59-7a2af0691c88",
            "sourceCidr": "10.2.1.0/24",
            "protocol": "UDP",
            "startPort": "80",
            "endPort": "80",
            "state": "Active"
        }
}

GET /services/:service_code/:environment_name/ingressrules/:id

Retrieve an ingress rule by its id.

Attributes
id UUID	The id of the ingress rule
networkId string	The id of the isolated network the rule applies to
publicIp string	The public IP of this ingress rule
publicIpId UUID	The id of the public IP of this ingress rule
sourceCidr string	The source cidr
protocol string	The protocol the rule applies to. Possible values: TCP, UDP, ICMP
startPort string	The start port (for TCP/UDP protocols only). Can be empty for all ports.
endPort string	The end port (for TCP/UDP protocols only). Can be empty to match the start port value.
icmpType string	The ICMP type (for ICMP protocol only)
icmpCode string	The ICMP code (for ICMP protocol only)
state string	The state. Possible values: Active, Inactive

Create an ingress rule

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/ingressrules"

POST /services/:service_code/:environment_name/ingressrules

Required
networkId string	The id of the isolated network the rule applies to
sourceCidr string	The source cidr
protocol string	The protocols targeted by this rule (TCP, UDP, ICMP).

Protocol-specific
publicIpId UUID	The id of the public IP where the ingress be applied. If not provided, a new public IP will be acquired.
startPort string	The start of the port range targeted by this rule. Required if the protocol is TCP or UDP. If left empty, all ports will be opened.
endPort string	The end of the port range targeted by this rule. Only valid if the protocol is TCP or UDP. If left empty, it will match the startPort value.
icmpType string	ICMP message type. Required if the protocol is ICMP
icmpCode string	ICMP message error code. Required if the protocol is ICMP

Delete an ingress rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/ingressrules/3247167a-e7e7-11e3-9187-06669c0000ad"

DELETE /services/:service_code/:environment_name/ingressrules/:id

Delete a specific ingress rule.

Egress rules

Manage outbound traffic rules for isolated networks

List egress rules

curl -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/egressrules"

The above command returns a JSON structured like this:

{
    "data": [
       {
            "id": "f6c7f86f-1e28-42fd-804f-0416a201a778",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "sourceCidr": "10.2.1.0/25",
            "destinationCidr": "0.0.0.0/0",
            "protocol": "ALL",
            "state": "Active"
        },
        {
            "id": "d860f2e7-ad15-4cb0-8477-6aa439245d1f",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "sourceCidr": "10.2.1.0/24",
            "destinationCidr": "",
            "protocol": "ICMP",
            "icmpType": "3",
            "icmpCode": "5",
            "state": "Active",
            "allPortsAllowed": false
        },
        {
            "id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "sourceCidr": "10.2.1.0/24",
            "destinationCidr": "",
            "protocol": "UDP",
            "startPort": "",
            "endPort": "",
            "state": "Active",
            "allPortsAllowed": true
        }
    ],
    "metadata": {
        "recordCount": 3
    }
}

GET /services/:service_code/:environment_name/egressrules

List egress rules.

Attributes
id UUID	The id of the egress rule
networkId string	The id of the network the rule applies to
sourceCidr string	The source cidr
destinationCidr string	The destination cidr
protocol string	The protocol the rule applies to. Possible values: TCP, UDP, ICMP, ALL
startPort string	The start port (for TCP/UDP protocols only)
endPort string	The end port (for TCP/UDP protocols only)
allPortsAllowed boolean	The flag indicating all the port range selection (for TCP/UDP protocols only)
icmpType string	The ICMP type (for ICMP protocol only)
icmpCode string	The ICMP code (for ICMP protocol only)
state string	The state. Possible values: Active, Inactive

Query Parameters
network_id UUID	Filter the list to only retrieve the egress rules of a specific Network

Retrieve an egress rule

curl -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/egressrules/f1863d10-e7ec-4f17-8cdd-0e4046643b0b"

The above command returns a JSON structured like this:

{
    "data": {
            "id": "f1863d10-e7ec-4f17-8cdd-0e4046643b0b",
            "networkId": "858d3ab6-04c9-43ef-9e83-07f28df59323",
            "sourceCidr": "10.2.1.0/24",
            "destinationCidr": "",
            "protocol": "UDP",
            "startPort": "",
            "endPort": "",
            "state": "Active",
            "allPortsAllowed": true
        }
}

GET /services/:service_code/:environment_name/egressrules/:id

Retrieve an egress rule by its id.

Attributes
id UUID	The id of the egress rule
networkId string	The id of the network the rule applies to
sourceCidr string	The source cidr
destinationCidr string	The destination cidr
protocol string	The protocol the rule applies to
startPort string	The start port (for TCP/UDP protocols only)
endPort string	The end port (for TCP/UDP protocols only)
allPortsAllowed boolean	The flag indicating all the port range selection (for TCP/UDP protocols only)
icmpType string	The ICMP message type (for ICMP protocol only)
icmpCode string	The ICMP message error code (for ICMP protocol only)
state string	The state. Possible values: Active, Inactive

Create an egress rule

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/egressrules"

POST /services/:service_code/:environment_name/egressrules

Required
networkId string	The id of the network the rule applies to
sourceCidr string	The source cidr
protocol string	The protocols targeted by this rule. TCP, UDP, ICMP, or ALL

Optional
destinationCidr string	The destination cidr

Protocol-specific
startPort string	The start of the port range targeted by this rule. Required if the protocol is TCP or UDP
endPort string	The end of the port range targeted by this rule. Required if the protocol is TCP or UDP
allPortsAllowed boolean	The flag indicating the selection of all the port range, i.e. 1-65535. Required if the protocol is TCP or UDP. Default value: false
icmpType string	ICMP message type. Required if the protocol is ICMP
icmpCode string	ICMP message error code. Required if the protocol is ICMP

Delete an egress rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/egressrules/3247167a-e7e7-11e3-9187-06669c0000ad"

DELETE /services/:service_code/:environment_name/egressrules/:id

Delete a specific egress rule.

NICs

List NICs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/nics"

The above command returns a JSON structured like this:

{
  "data": [{
    "id": "fff1f45a-8350-4c87-be43-947b96d01ebd",
    "name": "NIC-0",
    "ipAddress": "10.169.253.165",
    "isDefault": true,
    "networkId": "d2243d4c-0dd8-4f8c-9ab4-4b1d285d5642",
    "networkName": "Backend",
    "gateway": "10.169.253.1",
    "netmask": "255.255.255.0",
    "instanceId": "b6145e8b-abd3ta-456c-832c-f3db86a6acfe",
    "vpcId": "5aa9f5d7-55a9-43bf-bd2c-78a6bae1b267",
    "vpcName": "default-vpc",
    "secondaryIps": [
      {
        "id": "9c28e297-5d23-41a3-a167-34dc24f1df19",
        "ipAddress": "10.169.253.124"
      }
    ]
  }],
  "metadata": {
    "recordCount": 1
  }
}

GET :service_code/:environment_name/nics

Retrieve a list of all NICs.

Attributes
id UUID	The id of the NIC
name string	The name of the NIC
ipAddress string	The IP address of the NIC
isDefault string	true if it's the default NIC of the instance (i.e. it will be the private IP on the instance)
networkId UUID	The id of the network of the NIC
networkName string	The name of the network of the NIC
gateway string	The gateway of the network associated with the NIC
netmask string	The netmask of the network associated with the NIC
instanceId string	The id of the instance associated with the NIC
vpcId string	The id of the VPC associated with the NIC
vpcName string	The name of the VPC associated with the NIC
secondaryIps SecondaryIP	The list of secondary IPs of the NIC includes: id, ipAddress

Query Parameters
instance_id UUID	Filter the list to only retrieve the NICs of a specific instance
network_id UUID	Filter the list to only retrieve the NICs of a specific network

Retrieve a NIC

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/nics/fff1f45a-8350-4c87-be43-947b96d01ebd"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "fff1f45a-8350-4c87-be43-947b96d01ebd",
    "name": "NIC-0",
    "ipAddress": "10.169.253.165",
    "isDefault": true,
    "networkId": "d2243d4c-0dd8-4f8c-9ab4-4b1d285d5642",
    "networkName": "Backend",
    "gateway": "10.169.253.1",
    "netmask": "255.255.255.0",
    "instanceId": "b6145e8b-abd3ta-456c-832c-f3db86a6acfe",
    "vpcId": "5aa9f5d7-55a9-43bf-bd2c-78a6bae1b267",
    "vpcName": "default-vpc",
    "secondaryIps": [
      {
        "id": "9c28e297-5d23-41a3-a167-34dc24f1df19",
        "ipAddress": "10.169.253.124"
      }
    ]
  }
}

GET /services/:service_code/:environment_name/nics/:id

Retrieve an existing NIC.

Attributes
id UUID	The id of the NIC
name string	The name of the NIC
ipAddress string	The IP address of the NIC
isDefault string	true if it's the default NIC of the instance (i.e. it will be the private IP on the instance)
networkId UUID	The id of the network of the NIC
networkName string	The name of the network of the NIC
gateway string	The gateway of the network associated with the NIC
netmask string	The netmask of the network associated with the NIC
instanceId string	The id of the instance associated with the NIC
vpcId string	The id of the VPC associated with the NIC
vpcName string	The name of the VPC associated with the NIC
secondaryIps SecondaryIP	The list of secondary IPs of the NIC includes: id, ipAddress

Create a NIC

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/nics"

Request body example:

{
  "networkId": "d67e986d-fe04-4827-836e-1697ede8ed30",
  "instanceId": "96330eea-4424-46ca-825c-82fdd051d8c3"
}

POST /services/:service_code/:environment_name/nics

Create a NIC for an instance in a specific network. You can only have one NIC per network.

Required
networkId string	The id of the network where to create the NIC
instanceId string	The id of the instance where to attach the NIC

Delete a NIC

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/nics/63ef1efe-225f-4e05-bc79-b3e457a041e2"

DELETE /services/:service_code/:environment_name/nics/:id

Delete an existing NIC. The NIC you're trying to delete must not be the default one and must not be associated to a load balancing rule and/or a port forwarding rule.

Set a NIC as default

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/nics/63ef1efe-225f-4e05-bc79-b3e457a041e2?operation=setDefault"

POST /services/:service_code/:environment_name/nics/:id?operation=setDefault

Set an existing NIC as the default NIC of an instance.

Remote access VPNs

Remote access VPNs allow users to connect to VPCs through secure connections.

List remote access VPNs

curl -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/remoteaccessvpns"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
            "publicIpAddress": "69.196.164.31",
            "publicIpAddressId": "10001e7d-b4ef-489b-836e-0619a383bc8d",
            "state": "Disabled"
        },
        {
            "id": "8925406c-8051-467e-a0ca-c48caa5bf670",
            "presharedKey": "Kwth4JYUfXXmtMG4X7vAwRPH",
            "publicIpAddress": "69.196.164.223",
            "publicIpAddressId": "8925406c-8051-467e-a0ca-c48caa5bf670",
            "state": "Enabled"
        }
    ],
    "metadata": {
        "recordCount": 2
    }
}

GET /services/:service_code/:environment_name/remoteaccessvpns

List remote access VPNs.

Attributes
id UUID	The id of the remote access VPN
presharedKey string	The VPN's preshared key
publicIpAddress string	The public IP (e.g. 208.80.154.224)
publicIpAddressId string	The id of the public IP
state string	The state. Possible values: Enabled, Disabled.

Query Parameters
vpc_id UUID	Filter the list to only retrieve the VPN information of a specific VPC
network_id UUID	Filter the list to only retrieve the VPN information of a specific Network

Retrieve a remote access VPN

curl -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/remoteaccessvpns/10001e7d-b4ef-489b-836e-0619a383bc8d"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "10001e7d-b4ef-489b-836e-0619a383bc8d",
        "publicIpAddress": "69.196.164.31",
        "publicIpAddressId": "10001e7d-b4ef-489b-836e-0619a383bc8d",
        "state": "Disabled"
    }
}

GET /services/:service_code/:environment_name/remoteaccessvpns/:id

Retrieve a remote access VPN.

Attributes
id UUID	The id of the remote access VPN
presharedKey string	The VPN's preshared key
publicIpAddress string	The public IP (e.g. 208.80.154.224)
publicIpAddressId string	The id of the public IP
state string	The state. Possible values: Enabled, Disabled.

VPN users

VPN users are the accounts that are allowed to connect to remote access VPNs.

List VPN users

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpnusers"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "5de76bf5-9f61-487a-a989-042b52882da4",
            "username": "wilson"
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/vpnusers

List VPN users.

Attributes
id UUID	The id of the remote access VPN user
username string	The VPN user's username

Retrieve a VPN user

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpnusers/5de76bf5-9f61-487a-a989-042b52882da4"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "5de76bf5-9f61-487a-a989-042b52882da4",
        "username": "wilson"
    }
}

GET /services/:service_code/:environment_name/vpnusers/:id

Retrieve a VPN user.

Attributes
id UUID	The id of the remote access VPN user
username string	The VPN user's username

Delete a VPN user

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpnusers/5de76bf5-9f61-487a-a989-042b52882da4"

DELETE /services/:service_code/:environment_name/vpnusers/:id

Delete an existing remote access VPN user.

Site-to-site VPNs

A site-to-site VPN allows multiple sites to establish a secure connection over the public network. In our case, we are talking about a secure connection between your VPC and another network (e.g. VPC, offices).

List site-to-site VPNs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sitetositevpns"

The above command returns a JSON structured like this:

{
  "data": [
    {
        "id": "d49b2922-0581-4587-94df-6fe719327d0f",
        "name": "stargate",
        "state": "Connected",
        "vpcId": "3fe7d82a-f4c4-4552-ac3b-787fdafed4e7",
        "gateway":"19.19.19.19",
        "cidrList":"10.12.0.2/22,10.0.0.0/24",
        "ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
        "ikeEncryptionAlgorithm": "aes256",
        "ikeHashAlgorithm": "sha1",
        "ikeDhGroup":"modp1536",
        "ikeLifetime":86400,
        "espEncryptionAlgorithm":"aes256",
        "espHashAlgorithm":"sha1",
        "espPerfectForwardSecrecy":"modp1536",
        "espLifetime":3600,
        "dpd": false,
        "forceEncap": false
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/sitetositevpns

Retrieve a list of all site-to-site VPNs in an environment.

Attributes
id UUID	The id of the site-to-site VPN
name string	The name of the site-to-site VPN
state string	The state of the site-to-site VPN. Can be Connected, Pending, Disconnected or Error. If disconnected, you can try to use the reset operation
vpcId UUID	The VPC for which the site-to-site VPN was created.
gateway string	The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment
cidrList string	Comma-separated list of CIDRs of the networks you want to connect to.
ipSecPsk string	IPSec pre-shared key.
ikeEncryptionAlgorithm string	The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
ikeHashAlgorithm string	The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5.
ikeDhGroup string	A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
ikeLifetime integer	The phase-1 lifetime of the security association in seconds.
espEncryptionAlgorithm string	Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
espHashAlgorithm string	Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5.
espPerfectForwardSecrecy string	Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
espLifetime integer	The phase-2 lifetime of the security association in seconds
dpd boolean	A method to detect an unavailable Internet Key Exchange (IKE) peer.
forceEncap boolean	Force encapsulation for NAT Traversal

Query Parameters
vpc_id UUID	Filter the list to only retrieve the site-to-site VPNs of a VPC

Retrieve a site-to-site VPN

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sitetositevpns/d49b2922-0581-4587-94df-6fe719327d0f"

The above command returns a JSON structured like this:

{
  "data": {
      "id": "d49b2922-0581-4587-94df-6fe719327d0f",
      "name": "stargate",
      "state": "Connected",
      "vpcId": "3fe7d82a-f4c4-4552-ac3b-787fdafed4e7",
      "gateway":"19.19.19.19",
      "cidrList":"10.12.0.2/22,10.0.0.0/24",
      "ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
      "ikeEncryptionAlgorithm": "aes256",
      "ikeHashAlgorithm": "sha1",
      "ikeDhGroup":"modp1536",
      "ikeLifetime":86400,
      "espEncryptionAlgorithm":"aes256",
      "espHashAlgorithm":"sha1",
      "espPerfectForwardSecrecy":"modp1536",
      "espLifetime":3600,
      "dpd": false,
      "forceEncap": false
  }
}

GET /services/:service_code/:environment_name/sitetositevpns/:id

Retrieve information about a site-to-site VPN.

Attributes
id UUID	The id of the site-to-site VPN
name string	The name of the site-to-site VPN
state string	The state of the site-to-site VPN. Can be Connected, Pending, Disconnected or Error. If disconnected, you can try to use the reset operation
vpcId UUID	The VPC for which the site-to-site VPN was created.
gateway string	The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment
cidrList string	Comma-separated list of CIDRs of the networks you want to connect to.
ipSecPsk string	IPSec pre-shared key.
ikeEncryptionAlgorithm string	The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
ikeHashAlgorithm string	The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5.
ikeDhGroup string	A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
ikeLifetime integer	The phase-1 lifetime of the security association in seconds.
espEncryptionAlgorithm string	Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
espHashAlgorithm string	Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5.
espPerfectForwardSecrecy string	Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
espLifetime integer	The phase-2 lifetime of the security association in seconds
dpd boolean	A method to detect an unavailable Internet Key Exchange (IKE) peer.
forceEncap boolean	Force encapsulation for NAT Traversal

Create a site-to-site VPN

# Here is the absolute minimum information required to create a new site-to-site VPN:
curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sitetositevpns"

Request body example:

{
      "name": "stargate",
      "vpcId": "3fe7d82a-f4c4-4552-ac3b-787fdafed4e7",
      "gateway":"19.19.19.19",
      "cidrList":"10.12.0.2/22,10.0.0.0/24",
      "ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
      "ikeEncryptionAlgorithm": "aes256",
      "ikeHashAlgorithm": "sha1",
      "ikeDhGroup":"modp1536",
      "ikeLifetime":86400,
      "espEncryptionAlgorithm":"aes256",
      "espHashAlgorithm":"sha1",
      "espPerfectForwardSecrecy":"modp1536",
      "espLifetime":3600,
      "dpd": false,
      "forceEncap": false
  }

POST /services/:service_code/:environment_name/sitetositevpns

Create a site-to-site VPN.

Required
name string	The name of the site-to-site VPN. Must be unique in the environment.
vpcId UUID	The VPC for which the site-to-site VPN was created.
gateway string	The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment
cidrList string	Comma-separated list of CIDRs of the networks you want to connect to.
ipSecPsk string	IPSec pre-shared key.
ikeEncryptionAlgorithm string	The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
ikeHashAlgorithm string	The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5.
ikeDhGroup string	A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
ikeLifetime integer	The phase-1 lifetime of the security association in seconds.
espEncryptionAlgorithm string	Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
espHashAlgorithm string	Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5.
espPerfectForwardSecrecy string	Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
espLifetime integer	The phase-2 lifetime of the security association in seconds

Optional

dpd
boolean | A method to detect an unavailable Internet Key Exchange (IKE) peer. Defaults to false forceEncap
boolean | Force encapsulation for NAT Traversal. Defaults to false

Update a site-to-site VPN

# Here is the absolute minimum information required to update a site-to-site VPN:
curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sitetositevpns/d49b2922-0581-4587-94df-6fe719327d0f"

Request body example:

{
      "name": "stargate",
      "gateway":"19.19.19.19",
      "cidrList":"10.12.0.2/22,10.0.0.0/24",
      "ipSecPsk": "WtOBS9GRux2XtJPtHY2TUvrv",
      "ikeEncryptionAlgorithm": "aes256",
      "ikeHashAlgorithm": "sha1",
      "ikeDhGroup":"modp1536",
      "ikeLifetime":86400,
      "espEncryptionAlgorithm":"aes256",
      "espHashAlgorithm":"sha1",
      "espPerfectForwardSecrecy":"modp1536",
      "espLifetime":3600,
      "dpd": false,
      "forceEncap": false
  }

POST /services/:service_code/:environment_name/sitetositevpns/:id

Update a site-to-site VPN.

Optional
name string	The name of the site-to-site VPN. Must be unique in the environment.
gateway string	The gateway of the network you want to connect to. NOTE: you cannot use a gateway that has already been used by a site-to-site VPN in your environment
cidrList string	Comma-separated list of CIDRs of the networks you want to connect to.
ipSecPsk string	IPSec pre-shared key.
ikeEncryptionAlgorithm string	The Internet Key Exchange (IKE) policy for phase-1. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
ikeHashAlgorithm string	The IKE hash for phase-1. The supported hash algorithms are SHA1 and MD5.
ikeDhGroup string	A public-key cryptography protocol which allows two parties to establish a shared secret over an insecure communications channel. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
ikeLifetime integer	The phase-1 lifetime of the security association in seconds.
espEncryptionAlgorithm string	Encapsulating Security Payload (ESP) algorithm within phase-2. The supported encryption algorithms are AES128, AES192, AES256, and 3DES.
espHashAlgorithm string	Encapsulating Security Payload (ESP) hash for phase-2. Supported hash algorithms are SHA1 and MD5.
espPerfectForwardSecrecy string	Perfect Forward Secrecy (or PFS) is the property that ensures that a session key derived from a set of long-term public and private keys will not be compromised. The supported options are Group-5 (1536-bit) and Group-2 (1024-bit).
espLifetime integer	The phase-2 lifetime of the security association in seconds
dpd boolean	A method to detect an unavailable Internet Key Exchange (IKE) peer. Defaults to false
forceEncap boolean	Force encapsulation for NAT Traversal. Defaults to false

Delete a site-to-site VPN

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sitetositevpns/d49b2922-0581-4587-94df-6fe719327d0f"

DELETE /services/:service_code/:environment_name/sitetositevpns/:id

Delete an existing site-to-site VPN.

Reset the connection of a site-to-site VPN

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/sitetositevpns/ca86b14f-20db-463d-b58a-9d3fa5959af2?operation=reset"

POST /services/:service_code/:environment_name/sitetositevpns/:id?operation=reset

Reset a site-to-site VPN.

Storage

Volumes

A volume is a virtual disk that provide storage for your instances. An OS volumes is created for every instance and it holds the OS of the instance. The size of this volume is usually pretty. A data volume is a volume that can be created and attached to an instance. It can also be detached and reattached to another instance.

List volumes

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/volumes"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
      "name": "DOUGLAS-ADM",
      "type": "os",
      "creationDate": "2016-10-19T14:25:41-0400",
      "instanceId": "b6145e8b-abd3-456c-832c-f3db86a6acfe",
      "instanceName": "i-douglas-ADM",
      "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
      "zoneName": "QC-1",
      "state": "Ready",
      "sizeInGb": 40
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/volumes

Retrieve a list of all volumes in an environment.

Attributes
id UUID	The id of the volume
name string	The name of the volume
type string	The type of the volume. os if it is a root volume of an instance, data otherwise
creationDate string	The creation date of the volume
instanceId UUID	The id of the instance to which the volume is attached
instanceName string	The name of the instance to which the volume is attached
zoneId UUID	The id of the zone where the volume was created
zoneName string	The name of the zone where the volume was created
state string	The state of the volume
sizeInGb integer	The size in gigabytes of the volume

Query Parameters
type string	Filter the list to only retrieve the volumes of a specific type (os or data)
instance_id UUID	Filter the list to only retrieve the volumes of a specific instance

Retrieve a volume

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/volumes/1bd672f4-b274-4371-a792-b0a6c6778cc7"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
    "name": "deep_thought_42",
    "type": "data",
    "creationDate": "2016-10-19T14:25:41-0400",
    "instanceId": "b6145e8b-abd3-456c-832c-f3db86a6acfe",
    "instanceName": "i-douglas-ADM",
    "zoneId": "04afdbd1-e32d-4999-86d0-96703736dded",
    "zoneName": "QC-1",
    "diskOfferingId": "21ba9c9b-a31e-496e-983f-e3041525bf95",
    "diskOfferingName": "50GB - 50 IOPS Min.",
    "state": "Ready",
    "sizeInGb": 40
  }
}

GET /services/:service_code/:environment_name/volumes/:id

Retrieve information about an volume.

Attributes
id UUID	The id of the volume
name string	The name of the volume
type string	The type of the volume. os if it is a root volume of an instance, data otherwise
creationDate string	The creation date of the volume
instanceId UUID	The id of the instance to which the volume is attached
instanceName string	The name of the instance to which the volume is attached
zoneId UUID	The id of the zone where the volume was created
zoneName string	The name of the zone where the volume was created
state string	The state of the volume
sizeInGb integer	The size in gigabytes of the volume

Create a volume

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/volumes"

Request body example:

{
   "name": "my_volume",
   "diskOfferingId": "166f85eb-b4a2-4000-8e0c-24104d551f60",
   "instanceId": "c043e651-8b3f-4941-b47f-5ecb77f3423b"
}

POST /services/:service_code/:environment_name/volumes

Create a volume in an environment. It will attached to the specified instance.

Required
name string	The name of the new volume
diskOfferingId UUID	The disk offering to use for the volume
instanceId UUID	The id of the instance to which the created volume will be attached

Delete a volume

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/volumes/e922e5fc-8fee-4688-ad93-c9ef5d7eb685"

DELETE /services/:service_code/:environment_name/volumes/:id

Destroy an existing data volume. A volume can only be deleted if it's not attached to an instance.

Attach a volume to an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/volumes/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=attachToInstance"

Request body example:

{
   "instanceId": "c043e651-8b3f-4941-b47f-5ecb77f3423b"
}

POST /services/:service_code/:environment_name/volumes/:id?operation=attachToInstance

Attach an existing data volume to an instance.

Required
instanceId UUID	The id of the instance to which the created volume should be attached

Detach a volume from an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/volumes/e922e5fc-8fee-4688-ad93-c9ef5d7eb685?operation=detachFromInstance"

POST /services/:service_code/:environment_name/volumes/:id?operation=detachFromInstance

Detach a data volume from an instance.

Create a volume snapshot

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/volumes/4fe54594-a788-442c-b7a8-0237f7a4f70d?operation=createSnapshotFromVolume"

Request body example:

{
   "snapshot": {
      "name": "PreMigrationState",
      "rapid": true
   }
}

POST /services/:service_code/:environment_name/volumes/:id?operation=createSnapshotFromVolume

Create a snapshot of an existing volume. Note that the volume must be in its READY state to be able to take a snapshot of it.

Optional
name string	A unique name to be given to the newly created snapshot. If this parameter is not provided then by default the concatenation of the instance name, volume name and the current timestamp is used. Eg:     [instance.name]_[volume.name]_[timestamp]     i-root-6E7_RapidVol_20190117153537
rapid boolean	Indicates the location as to where the snapshot is supposed to be made. Setting this to true will ensure that the snapshot is created in the same primary storage as where the volume is. If false, then the snapshot is created in a secondary storage. Note: Rapid snapshots enable much faster volume and template creation than from regular snapshots, but at a higher expense. Not all volumes support the rapid snapshot option.

Snapshots

A volume snapshot is a full image of a volume. They are often considered as backups, but in reality this is not 100% true since you have only the data written on disk. Volume Snapshots are typically used to derive new templates out of a running instance.

List snapshots

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/snapshots"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "33a27b8d-5a27-42a5-aec4-37606e372bda",
      "name": "i-douglas-ADM_foo_20161116211009",
      "state": "BackedUp",
      "intervalType": "MANUAL",
      "volumeId": "c779ca42-6966-41af-a7dc-23db4e41d4ee",
      "volume": "ROOT-35545",
      "volumeType": "ROOT-35545"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/snapshots

Retrieve a list of all snapshots in an environment.

Attributes
id UUID	The id of the snapshot
name string	The name of the snapshot
state string	The state of the snapshot
intervalType string	The interval type. MANUAL means that you created the snapshot manually (i.e. it's not a recurring snapshot)
volumeId UUID	The id of the volume that was snapshotted
volume string	The name of the volume that was snapshotted
volumeType string	The type of the volume that was snapshotted

Query Parameters
volume_id UUID	Filter the list to only retrieve the snapshots of a specific volume

Retrieve a snapshot

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/snapshots/1bd672f4-b274-4371-a792-b0a6c6778cc7"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "33a27b8d-5a27-42a5-aec4-37606e372bda",
    "name": "i-douglas-ADM_foo_20161116211009",
    "state": "BackedUp",
    "intervalType": "MANUAL",
    "volumeId": "c779ca42-6966-41af-a7dc-23db4e41d4ee",
    "volume": "ROOT-35545",
    "volumeType": "ROOT-35545"
  }
}

GET /services/:service_code/:environment_name/snapshots/:id

Retrieve information about a snapshot.

Attributes
id UUID	The id of the snapshot
name string	The name of the snapshot
state string	The state of the snapshot
intervalType string	The interval type. MANUAL means that you created the snapshot manually (i.e. it's not a recurring snapshot)
volumeId UUID	The id of the volume that was snapshotted
volume string	The name of the volume that was snapshotted
volumeType string	The type of the volume that was snapshotted

Create a snapshot

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/testing/snapshots?operation=create"

Request body example:

{
  "volumeId": "4fe54594-a788-442c-b7a8-0237f7a4f70d",
  "name": "BeforeUpgradeToV2",
  "rapid": true
}

POST /services/:service_code/:environment_name/snapshots?operation=create

Create a snapshot of an existing volume. Note that the volume must be in its READY state to be able to take a snapshot of it. You can get a list of volumes using this API.

Required
volumeId UUID	The id of the volume on which the snapshot is to be taken.

Optional
name string	A unique name to be given to the newly created snapshot. If this parameter is not provided then by default the concatenation of the instance name, volume name and the current timestamp is used. Eg:     [instance.name]_[volume.name]_[timestamp]     i-root-6E7_RapidVol_20190117153537
rapid boolean	Indicates the location as to where the snapshot is supposed to be created. Setting this to true will ensure that the snapshot is created in the same primary storage as where the volume is. If false, then the snapshot is created in a secondary storage.

Offerings

Offerings are what determine the characteristics of provisioned resources. There are 4 types of offerings : compute, disk, VPC and network offerings.

VPC offerings

VPC offerings determine which services are available to provisioned VPCs.

List VPC offerings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcofferings"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "41ac6ba0-6172-4bc4-bff6-b0831b91677c",
            "name": "Default VPC offering",
            "services": [
                "PortForwarding",
                "Vpn",
                "SourceNat",
                "Dhcp",
                "NetworkACL",
                "Dns",
                "Lb",
                "UserData",
                "StaticNat"
            ],
            "state": "Enabled"
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/vpcofferings

Retrieve a list of available VPC offerings.

Attributes
id UUID	The id of the VPC offering
name string	The name of the VPC offering
services Array[string]	The services provided by the offering
state string	The state of the offering

Retrieve a VPC offering

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/vpcofferings/41ac6ba0-6172-4bc4-bff6-b0831b91677c"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "41ac6ba0-6172-4bc4-bff6-b0831b91677c",
        "name": "Default VPC offering",
        "services": [
            "PortForwarding",
            "Lb",
            "NetworkACL",
            "SourceNat",
            "Dns",
            "StaticNat",
            "Vpn",
            "Dhcp",
            "UserData"
        ],
        "state": "Enabled"
    }
}

GET /services/:service_code/:environment_name/vpcofferings/:id

Retrieve a VPC offering.

Attributes
id UUID	The id of the VPC offering
name string	The name of the VPC offering
services Array[string]	The services provided by the offering
state string	The state of the offering

Network offerings

Network offerings determine which services are available to each provisioned network.

List network offerings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkofferings"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "89724d35-b69c-418c-be81-7d83fcfc9da9",
            "name": "Load Balanced Tier",
            "vpcOnly": true,
            "services": [
                "PortForwarding",
                "Vpn",
                "SourceNat",
                "Dhcp",
                "NetworkACL",
                "Dns",
                "Lb",
                "UserData",
                "StaticNat"
            ],
            "state": "ENABLED"
        },
        {
            "id": "087502ea-cb42-421b-9bd9-9cf9ae5d1b89",
            "name": "Standard Tier",
            "vpcOnly": true,
            "services": [
                "PortForwarding",
                "Vpn",
                "SourceNat",
                "Dhcp",
                "NetworkACL",
                "Dns",
                "UserData",
                "StaticNat"
            ],
            "state": "ENABLED"
        },
        {
            "id": "0f1b9d72-b842-11e7-abc4-cec278b6b50a",
            "name": "Isolated network",
            "vpcOnly": false,
            "services": [
                "PortForwarding",
                "SourceNat",
                "Dhcp",
                "Dns",
                "UserData",
                "StaticNat"
            ],
            "state": "ENABLED"
        }
    ],
    "metadata": {
        "recordCount": 3
    }
}

GET /services/:service_code/:environment_name/networkofferings

Retrieve a list of available network offerings.

Attributes
id UUID	The id of the network offering
name string	The name of the network offering
vpcOnly boolean	Whether or not the offering is for VPC subnets
services Array[string]	The services provided by the offering
state string	The state of the offering

Retrieve a network offering

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/networkofferings/89724d35-b69c-418c-be81-7d83fcfc9da9"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "89724d35-b69c-418c-be81-7d83fcfc9da9",
        "name": "Load Balanced Tier",
        "vpcOnly": true,
        "services": [
            "PortForwarding",
            "Lb",
            "NetworkACL",
            "SourceNat",
            "Dns",
            "StaticNat",
            "Vpn",
            "Dhcp",
            "UserData"
        ],
        "state": "ENABLED"
    }
}

GET /services/:service_code/:environment_name/networkofferings/:id

Retrieve a network offering.

Attributes
id UUID	The id of the network offering
name string	The name of the network offering
vpcOnly boolean	Whether or not the offering is for VPC subnets
services Array[string]	The services provided by the offering
state string	The state of the offering

Compute offerings

Compute offerings determine the number of vCPUs and the size of the memory allocated to new instances.

List compute offerings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/computeofferings"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "40a2e5f7-22e6-4d1e-b03b-4a4b7c9cbc6f",
            "name": "Custom CPU and memory",
            "custom" : true,
            "availableCpuCountValues": [1, 2, 4, 8],
            "availableMemoryInMBValues": [1024, 2048, 4096, 8192],
            "maxMemoryInMBToCpuRatio": 2048
        },
        {
            "id": "1fb0caba-8ffb-4e77-8dcb-401170e15e0a",
            "name": "1vCPU.1GB",
            "cpuCount": 1,
            "memoryInMB": 1024,
            "custom" : false
        },
        {
            "id": "37dabe14-1b7f-4f40-ab87-b3ab90c2e871",
            "name": "32 CPU - 256 GB RAM",
            "memoryInMB": 262144,
            "cpuCount": 32,
            "custom": false,
            "type": "BareMetal",
            "availabilityCount": 1
        }
    ],
    "metadata": {
        "recordCount": 3
    }
}

GET /services/:service_code/:environment_name/computeofferings

Retrieve a list of available compute offerings.

Attributes
id UUID	The id of the compute offering
name string	The name of the compute offering
availabilityCount integer	The number of compute offerings available to acquire. Only present for bare metal compute offerings.
availableCpuCountValues Array[integer]	The list of valid cpu counts when used in the create instance operation. Only present for custom offerings
availableMemoryInMBValues Array[integer]	The list of valid amounts of memory (in MB) that can be used in the create instance operation. Only present for custom offerings
cpuCount int	The number of vCPUs available to the created instance
custom boolean	If true, the cpuCount and memoryInMB fields will be missing from the response and will be required on instance create
maxMemoryInMBToCpuRatio integer	The maximum ratio of memory (in MB) to number of CPU of an instance created with this offering. Only present for custom offerings.
memoryInMB int	The amount of provisioned memory in MB
type enum	The type of compute offering. Only present for bare metal compute offerings. Value is BareMetal.

Retrieve a compute offering

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/computeofferings/40a2e5f7-22e6-4d1e-b03b-4a4b7c9cbc6f"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "40a2e5f7-22e6-4d1e-b03b-4a4b7c9cbc6f",
        "name": "1vCPU.512MB",
        "cpuCount": 1,
        "memoryInMB": 512,
        "custom": false
    }
}

GET /services/:service_code/:environment_name/computeofferings/:id

Retrieve a compute offering.

Attributes
id UUID	The id of the compute offering
name string	The name of the compute offering
availabilityCount integer	The number of compute offerings available to acquire. Only present for bare metal compute offerings.
availableCpuCountValues Array[integer]	The list of valid cpu counts when used in the create instance operation. Only present for custom offerings
availableMemoryInMBValues Array[integer]	The list of valid amounts of memory (in MB) that can be used in the create instance operation. Only present for custom offerings
cpuCount int	The number of vCPUs available to the created instance
custom boolean	If true, the cpuCount and memoryInMB fields will be missing from the response and will be required on instance create
maxMemoryInMBToCpuRatio integer	The maximum ratio of memory (in MB) to number of CPU of an instance created with this offering. Only present for custom offerings.
memoryInMB int	The amount of provisioned memory in MB
type enum	The type of compute offering. Only present for bare metal compute offerings. Value is BareMetal.

Disk offerings

Disk offerings determine the size and the performance (IOPS) of data volumes.

List disk offerings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/diskofferings"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "customIops": false,
            "customSize": false,
            "gbSize": 20,
            "id": "18bbab50-8d85-4b34-8361-0dc223ffd7e5",
            "name": "20GB - 20 IOPS Min."
        },
        {
            "customIops": false,
            "customSize": false,
            "gbSize": 50,
            "id": "0432acc2-9226-4945-bf2e-9c8157be31d1",
            "name": "50GB - 50 IOPS Min."
        }
    ],
    "metadata": {
        "recordCount": 2
    }
}

GET /services/:service_code/:environment_name/diskofferings

Retrieve a list of available disk offerings.

Attributes
id UUID	The id of the disk offering
name string	The name of the disk offering
gbSize int	The size of the data volume in GB
customSize boolean	If the offering supports custom size
customIops boolean	If the offering supports custom IOPS

Retrieve a disk offering

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/diskofferings/18bbab50-8d85-4b34-8361-0dc223ffd7e5"

The above command returns a JSON structured like this:

{
    "data": {
        "customIops": false,
        "customSize": false,
        "gbSize": 20,
        "id": "18bbab50-8d85-4b34-8361-0dc223ffd7e5",
        "name": "20GB - 20 IOPS Min."
    }
}

GET /services/:service_code/:environment_name/diskofferings/:id

Retrieve a disk offering.

Attributes
id UUID	The id of the disk offering
name string	The name of the disk offering
gbSize int	The size of the data volume in GB
customSize boolean	If the offering supports custom size
customIops boolean	If the offering supports custom IOPS

Zones

Each zone consists of physically isolated hosts, storage, and networking infrastructure. Like deploying workloads across regions, deploying workloads over multiple zones can help ensure high availability of applications.

List zones

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/zones"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
            "name": "ON-1"
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/zones

Retrieve a list of available zones.

Attributes
id UUID	The id of the zone
name string	The name of the zone

Retrieve a zone

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/compute-on/test_area/zones/ea901007-056b-4c50-bb3a-2dd635fce2ab"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "ea901007-056b-4c50-bb3a-2dd635fce2ab",
        "name": "ON-1"
    }
}

GET /services/:service_code/:environment_name/zones/:id

Retrieve a zone

Attributes
id UUID	The id of the zone
name string	The name of the zone

OpenStack plugin

The CloudMC OpenStack plugin incorporates various OpenStack services such as Nova and Neutron into CloudMC's API. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of OpenStack.

Instances

Deploy and manage your instances. Instances are virtual machines or physical machines managed by OpenStack.

List instances

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/instances"

The above command returns a JSON structured like this:

{
    "data": [
      {
         "id": "30fca349-68b0-48c2-9ada-1f60f57fa44e",
         "name": "nginx",
         "cpuCount": 2,
         "memoryInMB": 2048,
         "state": "active",
         "flavorId": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
         "flavorName": "2vCPU.2GB",
         "imageId": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
         "imageName": "ubuntu",
         "networkName": "web",
         "privateIpAddress": "192.168.0.11",
         "securityGroupNames": [
             "webServerSecGroup",
             "sshSecGroup"
         ],
        "updatedDate": "2020-04-15 14:38:32",
        "createdDate": "2020-04-15 14:37:53",
        "addresses": [
          {
            "networkId": "738f3944-e44c-4729-9fca-c6ade9235850",
            "networkName": "web",
            "portId": "08e7fabd-33ad-400c-a973-7bbf8cff51bc",
            "macAddress": "fa:16:3e:02:de:ae",
            "ipAddress": "10.55.84.72",
            "ipType": "fixed",
            "ipVersion": 4
          }
        ]
      }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/instances

Retrieve a list of all instances in an environment.

Attributes
id UUID	The id of the instance.
name string	The name of the instance.
state string	The current state of the instance.
flavorId UUID	The flavor id of the instance.
flavorName string	The flavor name of the instance.
imageId UUID	The image id of the instance.
imageName string	The image name of the instance.
cpuCount int	The number of vCPUs associated with the instance's flavor.
memoryInMB int	The number of megabytes associated with the instance's flavor.
networkId UUID	The id of the network where instance is deployed.
networkName string	The name of the network where instance is deployed.
privateIpAddress string	The instance's private IP address.
securityGroupNames Array[string]	The list of security groups associated to the instance.
createdDate string	The date the instance was created.
updatedDate string	The date the instance was updated.
addresses: Array[Object]	The list of addresses attached to the instance.
addresses.networkId: string	The id of the network.
addresses.networkName: string	The name of the network.
addresses.portId: string	The id of the port.
addresses.macAddress: string	The MAC address associated to the address.
addresses.ipAddress: string	The IP address.
addresses.ipType: string	The type of address. Possible values : fixed, floating.
addresses.ipVersion: integer	The version of the IP protocol.

Retrieve an instance

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e"

The above command returns a JSON structured like this:

{
   "data": {
      "id": "30fca349-68b0-48c2-9ada-1f60f57fa44e",
      "name": "nginx",
      "cpuCount": 2,
      "memoryInMB": 2048,
      "state": "active",
      "flavorId": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
      "flavorName": "2vCPU.2GB",
      "imageId": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
      "imageName": "ubuntu",
      "networkName": "web",
      "privateIpAddress": "192.168.0.11",
      "securityGroupNames": [
          "webServerSecGroup",
          "sshSecGroup"
      ],
      "updatedDate": "2020-04-15 14:38:32",
      "createdDate": "2020-04-15 14:37:53",
      "addresses": [
        {
          "networkId": "738f3944-e44c-4729-9fca-c6ade9235850",
          "networkName": "web",
          "portId": "08e7fabd-33ad-400c-a973-7bbf8cff51bc",
          "macAddress": "fa:16:3e:02:de:ae",
          "ipAddress": "10.55.84.72",
          "ipType": "fixed",
          "ipVersion": 4
        }
      ]
  }
}

GET /services/:service_code/:environment_name/instances/:id

Retrieve information about an instance.

Attributes
id UUID	The id of the instance.
name string	The name of the instance.
state string	The current state of the instance.
flavorId UUID	The flavor id of the instance.
flavorName string	The flavor name of the instance.
imageId UUID	The image id of the instance.
imageName string	The image name of the instance.
cpuCount int	The number of vCPUs associated with the instance's flavor.
memoryInMB int	The number of megabytes associated with the instance's flavor.
networkId UUID	The id of the network where instance is deployed.
networkName string	The name of the network where instance is deployed.
privateIpAddress string	The instance's private IP address.
securityGroupNames Array[string]	The list of security groups associated to the instance.
createdDate string	The date the instance was created.
updatedDate string	The date the instance was updated.
addresses: Array[Object]	The list of addresses attached to the instance.
addresses.networkId: string	The id of the network.
addresses.networkName: string	The name of the network.
addresses.portId: string	The id of the port.
addresses.macAddress: string	The MAC address associated to the address.
addresses.ipAddress: string	The IP address.
addresses.ipType: string	The type of address. Possible values : fixed, floating.
addresses.ipVersion: integer	The version of the IP protocol.

Create an instance

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/instances"

Request body example:

{
    "name": "web1",
    "imageId": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
    "flavorId": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
    "networkId": "2fc5a74b-26c9-4541-af3f-84ee4c75eb0c",
    "securityGroupNames": ["secGroupA", "secGroupB"]
}

POST /services/:service_code/:environment_name/instances

Create an instance in an environment.

Required
imageId UUID	The image to use for this instance.
flavorId UUID	The flavor will determine the number of CPU and RAM of your instance.
networkId UUID	The network in which the instance will be created. If you don't have a network, it can be created through the create network API.
securityGroupNames Array[string]	The list of security groups to be associated to the instance.

Optional
name string	Name of the instance.
userData string	Data that the user can specify when they launch an instance. User data can be used in the cloud-init system as a script that is run during the initial launch. The user data field can be used to configure SSH keys, user settings, or run a script.
sshKeyName string	Name of the ssh key to link to the instance.
volumeToAttach Object	Specifies that a volume must be attached a volume needs to be attached to the instance.
volumeToAttach.id Object	Id of an existing volume to attach to the instance.
volumeToAttach.sizeInGB Object	The size in GB of the new disk to attached to the instance.

Associate a floating IP

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e?operation=associate"

Request body example:

{
  "floatingIpId": "287a3963-983b-4602-9dea-4dff89e9dc10"
}

POST /services/:service_code/:environment_name/instances/:id?operation=associate

Associate a floating IP to an instance in your environment.

Required	Description
floatingIpId UUID	The ID of a previously-acquired floating IP.

Change security groups

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e?operation=changeSecurityGroups"

Request body example:

{
  "securityGroupNames": [ "securityGroupNameA", "securityGroupNameB"]
}

POST /services/:service_code/:environment_name/instances/:id?operation=changeSecurityGroups

Change the security groups of an instance to the ones specified in the request.

Required	Description
securityGroupNames Array[string]	A list of security group names that should be associated to the instance

Delete an instance

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/instances/30fca349-68b0-48c2-9ada-1f60f57fa44e"

DELETE /services/:service_code/:environment_name/instances/:id

Delete an instance.

Networks

Networks are provisioned to be able to control data flow to instances. To communicate with the external network, the network must be connected to a router.

List networks

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/networks"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "a9e8861d-64a1-4126-b385-6e4db9a5814f",
            "name": "default",
            "enabled": true,
            "external": false,
            "gateway": "10.55.84.1",
            "cidr": "10.55.84.0/22",
            "dhcpEnabled":true,
            "ipVersion": "V4",
            "subnetId": "bda27442-f6c8-4033-84f0-ffcf319228a4"        
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/networks

Retrieve a list of all networks in an environment.

Attribute	Description
id UUID	The network's id.
name string	The network's name.
enabled boolean	If the network is enabled.
external boolean	If the network is accessible from the external.
gateway string	The IP of the gateway.
cidr string	CIDR of the network.
dhcpEnabled boolean	If DHCP is handled by the network.
ipVersion string	V4 or V6.
subnetId string	The id of the OpenStack subnet it maps to.

Retrieve a network

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/networks/a9e8861d-64a1-4126-b385-6e4db9a5814f"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "a9e8861d-64a1-4126-b385-6e4db9a5814f",
        "name": "default",
        "enabled": true,
        "external": false,
        "gateway": "10.55.84.1",
        "cidr": "10.55.84.0/22",
        "dhcpEnabled":true,
        "ipVersion": "V4",
        "subnetId": "bda27442-f6c8-4033-84f0-ffcf319228a4"        
    }
}

GET /services/:service_code/:environment_name/networks/:id

Retrieve information about a network.

Attribute	Description
id UUID	The network's id.
name string	The network's name.
enabled boolean	If the network is enabled.
external boolean	If the network is accessible from the external.
gateway string	The IP of the gateway.
cidr string	CIDR of the network.
dhcpEnabled boolean	If DHCP is handled by the network.
ipVersion string	V4 or V6.
subnetId string	The id of the OpenStack subnet it maps to.

Create a network

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/networks"

Request body example:

{
    "name": "web",
    "cidr": "10.50.0.0/22",
    "dhcpEnabled":true
}

POST /services/:service_code/:environment_name/networks

Create a network in an environment.

Optional
name string	Name of the network
cidr string	The CIDR of the network. The mask should be between 1 and 30 inclusively. Example: 10.50.0.0/22
dhcpEnabled boolean	If DHCP should be enabled for the network or if it will be handled by the user
routerId string	The id of an existing router. If provided, it will create an interface on that router for the created network. It may not be provided with externalNetworkId
externalNetworkId string	The id of the external network. If provided, it will create a router connected to that external network and add an interface on that router for the created network. It may not be provided with routerId

N.B.: The name and cidr will be autogenerated if left blank. dhcpEnabled will default to false

Delete a network

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/networks/a9e8861d-64a1-4126-b385-6e4db9a5814f"

DELETE /services/:service_code/:environment_name/networks/:id

Delete a network.

Flavors

Flavors are available hardware configurations for instances. They store the information for compute and memory capacity.

List flavors

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/flavors"

The above command returns a JSON structured like this:

{
   "data": [
      {
         "id": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
         "name": "1vCPU.256MB",
         "ephemeralSizeInGB": 0,
         "diskSizeInGB": 20,
         "memorySizeInMB": 256,
         "cpuCount": 1
      },
      {
         "id": "921e8296-c801-498c-90a9-4398cd44681f",
         "name": "1vCPU.512MB",
         "ephemeralSizeInGB": 0,
         "diskSizeInGB": 20,
         "memorySizeInMB": 512,
         "cpuCount": 1
      }
   ],
   "metadata": {
      "recordCount": 2
   }
}

GET /services/:service_code/:environment_name/flavors

Retrieve a list of available flavors.

Attributes
id UUID	The flavor's id.
name string	The flavor name.
ephemeralSizeInGB string	The size of the ephemeral disk in GB.
diskSizeInGB string	The size of the root disk in GB.
memorySizeInMB string	The size of the memory in MB.
cpuCount string	The number of vCPU assigned.

Retrieve a flavor

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/flavors/1d547941-1738-4d7b-a70b-b52a44ff18e5"

The above command returns a JSON structured like this:

{
   "data": {
      "id": "1d547941-1738-4d7b-a70b-b52a44ff18e5",
      "name": "1vCPU.256MB",
       "ephemeralSizeInGB": 0,
       "diskSizeInGB": 20,
       "memorySizeInMB": 256,
       "cpuCount": 1
   }
}

GET /services/:service_code/:environment_name/flavors/:id

Retrieve information about a flavor.

Attributes
id UUID	The flavor's id.
name string	The flavor name.
ephemeralSizeInGB string	The size of the ephemeral disk in GB.
diskSizeInGB string	The size of the root disk in GB.
memorySizeInMB string	The size of the memory in MB.
cpuCount string	The number of vCPU assigned.

Images

Images are virtual machine images that have a virtual disk that contains a bootable operating system.

List images

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/images"

The above command returns a JSON structured like this:

{
   "data": [
      {
         "id": "22f53310-798d-4029-bb00-747a52d2a376",
         "name": "ubuntu"
      },
      {
         "id": "68f9027d-cf64-4648-a0fa-4667d5618b6b",
         "name": "centos7"
      }
   ],
   "metadata": {
      "recordCount": 2
   }
}

GET /services/:service_code/:environment_name/images

Retrieve a list of available images.

Attributes
id UUID	The image's id.
name string	The image name.

Retrieve an image

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/images/22f53310-798d-4029-bb00-747a52d2a376"

The above command returns a JSON structured like this:

{
   "data": {
      "id": "22f53310-798d-4029-bb00-747a52d2a376",
      "name": "ubuntu"
   }
}

GET /services/:service_code/:environment_name/images/:id

Retrieve information about an image.

Attributes
id UUID	The image's id.
name string	The image name.

Floating IPs

Floating IPs are public IP addresses that a user can acquire and use in an environment.

List floating IPs

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/floatingips"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "287a3963-983b-4602-9dea-4dff89e9dc10",
            "floatingIpAddress": "10.182.56.27",
            "fixedIpAddress": "10.0.0.8",
            "externalNetworkId": "963b6966-d9d7-48a8-8141-f414a809dbf4"
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/floatingips

Retrieve a list of all floating IPs in an environment.

Attributes
id UUID	The floating IP's id.
floatingIpAddress string	The floating IP's public IP address.
fixedIpAddress string	The fixed IP to which the floating IP is associated. This may be empty if the floating IP is not associated with an instance.
externalNetworkId UUID	The id of the external network to which the floating IP belongs.

Retrieve a floating IP

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/floatingips/287a3963-983b-4602-9dea-4dff89e9dc10"

The above command returns a JSON structured like this:

{
    "data": {
         "id": "287a3963-983b-4602-9dea-4dff89e9dc10",
         "floatingIpAddress": "10.182.56.27",
         "fixedIpAddress": "10.0.0.8",
         "externalNetworkId": "963b6966-d9d7-48a8-8141-f414a809dbf4"
    }
}

GET /services/:service_code/:environment_name/floatingips/:id

Retrieve information about a floating IP.

Attributes
id UUID	The floating IP's id.
floatingIpAddress string	The floating IP's public IP address.
fixedIpAddress string	The fixed IP to which the floating IP is associated. This may be empty if the floating IP is not associated with an instance.
externalNetworkId UUID	The id of the external network to which the floating IP belongs.

Acquire a floating IP

curl -X POST \
    -H "MC-Api-Key: your_api_key" \ 
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/floatingips"

Request body example:

{
    "externalNetworkId": "networkId",
}

POST /services/:service_code/:environment_name/floatingips

Acquire a floating IP in an environment.

Optional
externalNetworkId string	The external network id to associate the new floating ip. If there is more than one network, it will be required to specify it.

Release a floating IP

curl -X DELETE \
    -H "MC-Api-Key: your_api_key"
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/floatingips/287a3963-983b-4602-9dea-4dff89e9dc10"

DELETE /services/:service_code/:environment_name/floatingips/:id

Release a floating IP.

Security groups

Security groups manage network access to instances.

List security groups

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygroups"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
            "name": "default",
            "description": "Default security group",
            "isDefault": true
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/securitygroups

Retrieve a list of all security groups in an environment.

Attribute	Description
id UUID	The security group's id.
name string	The security group's name.
description string	A description of the group's purpose.
isDefault boolean	If the security group is the default.

Retrieve a security group

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygroups/1bd672f4-b274-4371-a792-b0a6c6778cc7"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "1bd672f4-b274-4371-a792-b0a6c6778cc7",
        "name": "default",
        "description": "Default security group",
        "isDefault": true
    }
}

GET /services/:service_code/:environment_name/securitygroups/:id

Retrieve information about a security group.

Attribute	Description
id UUID	The security group's id.
name string	The security group's name.
description string	A description of the group's purpose.
isDefault boolean	If the security group is the default.

Create a security group

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygroups"

Request body example:

{
    "name": "security-group-1",
    "description": "My very first security group"
}

POST /services/:service_code/:environment_name/securitygroups

Create a security group in an environment.

Required	Description
name string	The security group's name.
description string	A description of the group's purpose.

Delete a security group

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygroups/1bd672f4-b274-4371-a792-b0a6c6778cc7"

DELETE /services/:service_code/:environment_name/securitygroups/:id

Delete a security group.

Security group rules

Security group rules define the type of traffic that can access the instances associated with a security group.

List security group rules within a security group

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygrouprules?securitygroupid=f54f050b-01b2-4a73-b6e1-4e13a5566323"

The above command returns a JSON structured like this:

{
    "data": [
        {
          "id": "655d3bcb-3f8a-4738-b50a-53bca43469b5",
          "remoteAddress": "0.0.0.0/0",
          "startPort": 1,
          "endPort": 65535,
          "etherType": "IPv4",
          "protocol": "UDP",
          "ingress": true,
          "securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323"
        },
        {
          "id": "8d92b22b-b7d2-4584-865d-a9929cb1a24c",
          "remoteAddress": "0.0.0.0/0",
          "startPort": 15,
          "endPort": 30,
          "etherType": "IPv4",
          "protocol": "TCP",
          "ingress": true,
          "securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323"
        }
    ],
    "metadata": {
        "recordCount": 2
    }
}

GET /services/:service_code/:environment_name/securitygrouprules?securitygroupid=:securityGroupId

Retrieve a list of all security group rules in a security group.

Attribute	Description
id UUID	The security group rule's id.
remoteAddress string	Remote IPs or CIDRs associated with this rule.
startPort int	Minimum port that is matched by this rule.
endPort int	Maximum port that is matched by this rule.
etherType string	IP type, either IPv4 or IPv6.
protocol string	The IP protocol, either ICMP, TCP or UDP.
ingress boolean	Direction in which the rule is applied, false implies egress.
securityGroupId UUID	The ID of the parent security group.

Retrieve a security group rule

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygrouprules/655d3bcb-3f8a-4738-b50a-53bca43469b5"

The above command returns a JSON structured like this:

{
     "data": {
           "id": "655d3bcb-3f8a-4738-b50a-53bca43469b5",
           "remoteAddress": "0.0.0.0/0",
           "startPort": 1,
           "endPort": 65535,
           "etherType": "IPv4",
           "protocol": "ICMP",
           "ingress": true,
           "securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323"
      }
}

GET /services/:service_code/:environment_name/securitygrouprules/:id

Retrieve information about a security group rule.

Attribute	Description
id UUID	The security group rule's id.
remoteAddress string	Remote IPs or CIDRs associated with this rule.
startPort int	Minimum port that is matched by this rule.
endPort int	Maximum port that is matched by this rule.
etherType string	IP type, either IPv4 or IPv6.
protocol string	The IP protocol, either ICMP, TCP or UDP.
ingress boolean	Direction in which the rule is applied, false implies egress.
securityGroupId UUID	The ID of the parent security group.

Create a security group rule

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygrouprules"

Request body example:

{
    "ingress": true,
    "protocol": "UDP",
    "startPort": 10,
    "endPort": 20,
    "remoteAddress": "0.0.0.0/0",
    "securityGroupId": "f54f050b-01b2-4a73-b6e1-4e13a5566323",
}

POST /services/:service_code/:environment_name/securitygrouprules

Create a security group rule for a security group.

Required	Description
securityGroupId UUID	The ID of the parent security group.

Optional	Description
ingress boolean	Direction in which the rule is applied, false implies egress. Defaults to ingress.
protocol string	The IP protocol, either ICMP, TCP or UDP. Defaults to allow all protocols.
startPort int	Minimum port that is matched by this rule, required if end port specified. Defaults to 1.
endPort int	Maximum port that is matched by this rule. Defaults to 65535.
remoteAddress string	Remote IPs or CIDRs associated with this rule. Defaults to allow all IPs.

Delete a security group rule

curl -X DELETE \
    -H "MC-Api-Key: your_api_key"
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/securitygrouprules/655d3bcb-3f8a-4738-b50a-53bca43469b5"

DELETE /services/:service_code/:environment_name/securitygrouprules/:id

Delete a security group rule.

Routers

Routers route traffic between networks, including the public internet.

List routers

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routers"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "212eb8d8-80ee-4edd-8bae-1efed8bc5c71",
            "name": "external-router",
            "externalNetworkId": "167bea1e-f15a-41bd-8d54-44b613bfa36c",
            "externalNetworkName": "public-net",
            "networkNames": [
                "web",
                "data"
            ],
            "networkIds": [
                "4beaf851-c0d8-4ab7-9003-3b7c0e59f3d9",
                "68f97fb0-6a71-4be1-87bf-1c805940d2cb"
            ]
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/routers

Retrieve a list of routers in an OpenStack environment.

Attributes	Description
id UUID	The router's ID.
name string	The router's name.
networkIds Array[UUID]	The router's internal network IDs.
networkNames Array[string]	The router's internal network names.
externalNetworkId UUID	The router's external network ID.
externalNetworkName string	The router's external network name.

Retrieve a router

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routers/212eb8d8-80ee-4edd-8bae-1efed8bc5c71"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "212eb8d8-80ee-4edd-8bae-1efed8bc5c71",
        "name": "external-router",
        "externalNetworkId": "167bea1e-f15a-41bd-8d54-44b613bfa36c",
        "externalNetworkName": "public-net",
        "networkNames": [
            "web",
            "data"
        ],
        "networkIds": [
            "4beaf851-c0d8-4ab7-9003-3b7c0e59f3d9",
            "68f97fb0-6a71-4be1-87bf-1c805940d2cb"
        ]
    }
}

GET /services/:service_code/:environment_name/routers/:id

Retrieve a single router in an OpenStack environment.

Attributes	Description
id UUID	The router's ID.
name string	The router's name.
networkIds Array[UUID]	The router's internal network IDs.
networkNames Array[string]	The router's internal network names.
externalNetworkId UUID	The router's external network ID.
externalNetworkName string	The router's external network name.

Create a router

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routers"

Request body example:

{
    "name": "external-router",
    "externalNetworkId": "167bea1e-f15a-41bd-8d54-44b613bfa36c"
}

POST /services/:service_code/:environment_name/routers

Create a router.

Attributes	Description
name string	The router's name.
externalNetworkId UUID	The router's external network ID.

Add a router interface

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routers/212eb8d8-80ee-4edd-8bae-1efed8bc5c71?operation=addRouterInterface"

Request body example:

{
    "networkId": "471eb361-c028-45f5-bd1a-6d05a057624f",
}

POST /services/:service_code/:environment_name/routers/:id?operation=addRouterInterface

Connect a router to a network.

Attributes	Description
networkId UUID	The ID of the network to connect.

Delete a router

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routers/212eb8d8-80ee-4edd-8bae-1efed8bc5c71"

DELETE /services/:service_code/:environment_name/routers/:id

Delete a router.

Router interfaces

Router interfaces connect a router to a network.

List router interfaces

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routerinterfaces?routerid=3de4f523-06ce-4955-acb0-b8e3d61ec582"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
            "networkName": "test2",
            "networkId": "d507486c-eacb-48ff-841e-e3938213d95f",
            "portId": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
            "privateIp": "10.182.15.1",
            "routerId": "3de4f523-06ce-4955-acb0-b8e3d61ec582",
            "routerName": "routeName1"
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/routerinterfaces?routerid=:routerid

Retrieve a list of router interfaces associated with a router in an OpenStack environment.

Attributes	Description
id UUID	The router interface's ID.
networkName string	The name of the connected network.
networkId UUID	The ID of the connected network.
portId UUID	The ID of the port the interface is connected to (same as interface ID).
privateIp string	The private IP of the router interface.
routerId UUID	The ID of the parent router.
routerName UUID	The name of the parent router.

Retrieve a router interface

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routerinterfaces/b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
        "networkName": "test2",
        "networkId": "d507486c-eacb-48ff-841e-e3938213d95f",
        "portId": "b5f0cbbf-45f3-4e77-8a5c-90351f83e5f9",
        "privateIp": "10.182.15.1",
        "routerId": "3de4f523-06ce-4955-acb0-b8e3d61ec582",
        "routerName": "routeName1"
    }
}

GET /services/:service_code/:environment_name/routerinterfaces/:id

Retrieve a single router interface in an OpenStack environment.

Attributes	Description
id UUID	The router interface's ID.
networkName string	The name of the connected network.
networkId UUID	The ID of the connected network.
portId UUID	The ID of the port the interface is connected to (same as interface ID).
privateIp string	The private IP of the router interface.
routerId UUID	The ID of the parent router.
routerName UUID	The name of the parent router.

Create a router interface

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routerinterfaces"

Request body example:

{
    "networkId": "d507486c-eacb-48ff-841e-e3938213d95f",
    "routerId": "3de4f523-06ce-4955-acb0-b8e3d61ec582"
}

POST /services/:service_code/:environment_name/routerinterfaces

Create a router interface.

Required	Description
networkId UUID	The ID of the network that is being connected.
routerId UUID	The ID of the router.

Delete a router interface

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/routerinterfaces/c14ed06b-6de9-4b3e-aac9-9e6c1406de9e"

DELETE /services/:service_code/:environment_name/routerinterfaces/:id

Delete a router interface.

SSH keys

SSH keys can be assigned on instance creation to provide SSH access.

List SSH keys

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/sshkeys"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "ssh-key-a",
            "name": "ssh-key-a",
            "fingerprint": "17:43:84:aa:a1:ed:6b:aa:10:be:73:1f:63:d0:53:16",
            "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDlf6/L7kuWWyo8y718JXeKKJa5kdT5QT0GcJUVvuLGNAf/Xjwhc9ThaQk+5mBs49hECTTYlOP0J5lb69kpU2fCmRzroazMD8isOh33o7HdNT9F2CWEKCHJ4Qhd40bXf3b4twz43HIo/pkPyJZ7OVC1v39UNvSkh+iNdUkCVZAO9ijAeW4n+F6WSKG1GqZrdElGSMpTM/DMmNo393N3xOcW4Z9qjG7PGdPIgtxqM/wmyyv0id5eV/QkciOaVEgJ7jzQ/iQA1rdEPI7EojLFgaNTIRjp/fQ/BPQ47ZKimwRzns1csupr2BENDpAXqAqHTgSpEyeG/5OvD4oA521fLoiv Generated-by-Nova"
        },
        {
            "id": "ssh-key-b",
            "name": "ssh-key-b",
            "fingerprint": "2b:36:6b:f7:98:ef:6a:32:bf:c8:19:94:80:c1:44:60",
            "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCnZh9CoR97SY2gA7/JhShzNcxt0VVEi0QMOH/IJZWdu5mtSdJrIvZVTMVVKdae6PUQaYsVt5IImeOZLYiHkUNvvkm291BnKwuymjV9J/CftRs0ZM0X/VhftmROAT5G89Fw57VU6L6bjV4ex7fvAAhr44KJZsgViswOcxJSuwoGmQX15GJAxsSOQ4GthHWJWoifBG0la7+rtAPRUS/qAcCcVuaLNqTalSUtrAytD8J4tswd6UzzPf3MUJWMW36aExwhJW22oHQxvOSot2e36ZFhtHXj1PJs4ZG9mE9JMMz/Y9eIdHMg30vb/YQ5ftsJUs9xjjDD5+fjQxttB1QqqyCp Generated-by-Nova"
        }
    ],
    "metadata": {
        "recordCount": 2
    }
}

GET /services/:service_code/:environment_name/sshkeys

Retrieve a list of SSH keys in an OpenStack domain.

Attributes	Description
id string	The SSH key's ID which takes the same value as the name.
name string	The SSH key's name.
fingerprint string	A short sequence of bytes used to identify the SSH key.
publicKey string	The SSH public key.

Retrieve a SSH key

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/sshkeys/ssh-key-a"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "ssh-key-a",
        "name": "ssh-key-a",
        "fingerprint": "17:43:84:aa:a1:ed:6b:aa:10:be:73:1f:63:d0:53:16",
        "createDate": "2017-06-19T16:19:48.000Z",
        "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDlf6/L7kuWWyo8y718JXeKKJa5kdT5QT0GcJUVvuLGNAf/Xjwhc9ThaQk+5mBs49hECTTYlOP0J5lb69kpU2fCmRzroazMD8isOh33o7HdNT9F2CWEKCHJ4Qhd40bXf3b4twz43HIo/pkPyJZ7OVC1v39UNvSkh+iNdUkCVZAO9ijAeW4n+F6WSKG1GqZrdElGSMpTM/DMmNo393N3xOcW4Z9qjG7PGdPIgtxqM/wmyyv0id5eV/QkciOaVEgJ7jzQ/iQA1rdEPI7EojLFgaNTIRjp/fQ/BPQ47ZKimwRzns1csupr2BENDpAXqAqHTgSpEyeG/5OvD4oA521fLoiv Generated-by-Nova"
    }
}

GET /services/:service_code/:environment_name/sshkeys/:id

Retrieve a single SSH key in an OpenStack domain.

Attributes	Description
id string	The SSH key's ID which takes the same value as the name.
name string	The SSH key's name.
fingerprint string	A short sequence of bytes used to identify the SSH key.
createDate date	The date the SSH key was created.
publicKey string	The SSH public key.

Create a SSH key

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/sshkeys"

Request body example:

{
   "name": "ssh-key-c",
   "publicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDlf6/L7kuWWyo8y718JXeKKJa5kdT5QT0GcJUVvuLGNAf/Xjwhc9ThaQk+5mBs49hECTTYlOP0J5lb69kpU2fCmRzroazMD8isOh33o7HdNT9F2CWEKCHJ4Qhd40bXf3b4twz43HIo/pkPyJZ7OVC1v39UNvSkh+iNdUkCVZAO9ijAeW4n+F6WSKG1GqZrdElGSMpTM/DMmNo393N3xOcW4Z9qjG7PGdPIgtxqM/wmyyv0id5eV/QkciOaVEgJ7jzQ/iQA1rdEPI7EojLFgaNTIRjp/fQ/BPQ47ZKimwRzns1csupr2BENDpAXqAqHTgSpEyeG/5OvD4oA521fLoiv Generated-by-Nova"
}

POST /services/:service_code/:environment_name/sshkeys

Create a SSH key.

Required	Description
name string	The SSH key's name.
publicKey string	A public SSH key in RSA format.

Delete a SSH key

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/sshkeys/ssh-key-c"

DELETE /services/:service_code/:environment_name/sshkeys/:name

Delete a SSH key.

Volumes

Volumes are block-level storage devices that can be attached to instances.

List volumes

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes"

The above command returns a JSON structured like this:

{
   "data": [
      {
        "id": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
        "name": "web-data",
        "description": "Storage for the web server",
        "state": "available",
        "sizeInGB": 50
      }
   ],
   "metadata": {
      "recordCount": 1
   }
}

GET /services/:service_code/:environment_name/volumes

Retrieve a list of volumes.

Attributes
id UUID	The volume's id.
name string	The volume name.
description string	The volume's description.
sizeInGB integer	The volume's size in GB.
state string	The volume's state.
instanceId string	The instance id to which the volume is attached.
instanceName string	The instance name to which the volume is attached.
device string	The device under which the volume is The volume's state.

Retrieve a volume

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24"

The above command returns a JSON structured like this:

{
    "data": {
      "id": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
      "name": "web-data",
      "description": "Storage for the web server",
      "state": "available",
      "sizeInGB": 50
    }
}

GET /services/:service_code/:environment_name/volumes/:id

Retrieve a volume.

Attributes
id UUID	The volume's id.
name string	The volume name.
description string	The volume's description.
sizeInGB integer	The volume's size in GB.
state string	The volume's state.
instanceId string	The instance id to which the volume is attached.
instanceName string	The instance name to which the volume is attached.
device string	The device under which the volume is The volume's state.

Create a volume

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes"

Request body example:

{
   "name": "mysql",
   "description": "Production MySQL data",
   "sizeInGB":20
}

POST /services/:service_code/:environment_name/volumes

Create a volume.

Required	Description
name string	The volume name.
description string	The volume description.
sizeInGB integer	The volume's size in GB.

Delete a volume

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24"

DELETE /services/:service_code/:environment_name/volumes/:id

Delete a volume.

Attach a volume to an instance

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=attach"

Request body example:

{
   "instanceId": "449efafc-0a6f-4f9e-9602-4b9ac2400abd"
}

POST /services/:service_code/:environment_name/volumes/:id?operation=attach

Attach a volume to an instance.

Required	Description
instanceId UUID	The instance id.

Detach a volume from an instance

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=detach"

POST /services/:service_code/:environment_name/volumes/:id?operation=detach

Detach a volume from an instance.

Extend a volume

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=extend"

Request body example:

{
   "sizeInGB": 40
}

POST /services/:service_code/:environment_name/volumes/:id?operation=extend

Extend a volume size.

Required	Description
sizeInGB integer	The new size of the volume. It must be greater than the existing size.

Take a snapshot of a volume

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -H "Content-Type: application/json" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/volumes/52cfc2f8-5b1f-4833-83cd-a77f55c5ed24?operation=snapshot"

POST /services/:service_code/:environment_name/volumes/:id?operation=snapshot

Generate a snapshot of the volume.

Snapshots

Snapshots are point in time copies of volumes that can be used to create other volumes.

List Snapshots

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/snapshots"

The above command returns a JSON structured like this:

{
   "data": [
      {
        "id": "4b41c7de-b2a8-4cb7-82ce-46685b07921d",
        "name": "s-web-data-CJ6",
        "volumeId": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
        "volumeName": "web-data",
        "sizeInGB": 50,
        "state": "available"
      }
   ],
   "metadata": {
      "recordCount": 1
   }
}

GET /services/:service_code/:environment_name/snapshots

Retrieve a list of snapshots.

Attributes
id UUID	The snapshot's id.
name string	The snapshot name.
volumeId UUID	The volume's id.
volumeName string	The volume's name.
sizeInGB integer	The snapshot's size in GB.
state string	The snapshot's state.

Retrieve a snapshot

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/snapshots/4b41c7de-b2a8-4cb7-82ce-46685b07921d"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "4b41c7de-b2a8-4cb7-82ce-46685b07921d",
    "name": "s-web-data-CJ6",
    "volumeId": "52cfc2f8-5b1f-4833-83cd-a77f55c5ed24",
    "volumeName": "web-data",
    "sizeInGB": 50,
    "state": "available"
  }
}

GET /services/:service_code/:environment_name/snapshots/:id

Retrieve information about a snapshot.

Attributes
id UUID	The snapshot's id.
name string	The snapshot name.
volumeId UUID	The volume's id.
volumeName string	The volume's name.
sizeInGB integer	The snapshot's size in GB.
state string	The snapshot's state.

Delete a snapshot

curl -X DELETE \
    -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/compute-os/devel/snapshots/4b41c7de-b2a8-4cb7-82ce-46685b07921d"

DELETE /services/:service_code/:environment_name/snapshots/:id

Delete a snapshot.

Google Cloud Platform plugin

The Google Cloud Platform plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of GCP.

Compute

Instances

Deploy and manage your instances.

List instances

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "status": "RUNNING",
      "zone": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
      "machineType": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/machineTypes/f1-micro",
      "cpuPlatform": "Intel Skylake",
      "creationTimestamp": "2019-04-19T12:12:30.756-07:00",
      "deletionProtection": false,
      "disks": [
        {
          "autoDelete": true,
          "boot": true,
          "deviceName": "i-test-kkn",
          "guestOsFeatures": [
            {
              "type": "VIRTIO_SCSI_MULTIQUEUE"
            }
          ],
          "index": 0,
          "interface": "SCSI",
          "kind": "compute#attachedDisk",
          "licenses": [
            "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
          ],
          "mode": "READ_WRITE",
          "source": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/disks/i-test-kkn",
          "type": "PERSISTENT"
        }
      ],
      "kind": "compute#instance",
      "labelFingerprint": "42WmSpB8rSM=",
    "metadata": {
      "fingerprint": "RnfaWQ2UP4U=",
      "items": [
        {
          "key": "startup-script",
          "value": "#! /bin/bash\napt-get update\nEOF"
        }
      ],
      "kind": "compute#metadata"
    },
      "networkInterfaces": [
        {
          "accessConfigs": [
            {
              "kind": "compute#accessConfig",
              "name": "external-nat",
              "natIP": "35.203.99.102",
              "networkTier": "PREMIUM",
              "type": "ONE_TO_ONE_NAT"
            }
          ],
          "fingerprint": "NG6-4Cdf0KA=",
          "kind": "compute#networkInterface",
          "name": "nic0",
          "network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
          "networkIP": "10.162.0.7",
          "subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default"
        }
      ],
      "scheduling": {
        "automaticRestart": true,
        "onHostMaintenance": "MIGRATE",
        "preemptible": false
      },
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/instances/i-test-kkn",
      "startRestricted": false,
      "tags": {
        "fingerprint": "42WmSpB8rSM="
      },
      "shortMachineType": "custom-2-2048",
      "project": "test-area-oox",
      "internalIp": "10.162.0.7",
      "externalIp": "35.203.99.102",
      "shortNetwork": "default",
      "shortSubnetwork": "default",
      "iconUrl": "/rest/services/assets/gcp/os_logo/debian.png",
      "osImageName": "debian-9-stretch",
      "osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
      "osImageSizeInGb": 0,
      "bootDiskSizeInGb": 0,
      "cpuCount": 2,
      "memoryInGB": 2.000000,
      "id": "5611478403377505138",
      "name": "i-test-kkn",
      "shortZone": "northamerica-northeast1-a",
      "shortRegion": "northamerica-northeast1"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/instances

Retrieve a list of all instances in a given environment.

Attributes
status string	The status of the instance. One of the following values: PROVISIONING, STAGING, RUNNING, STOPPING, STOPPED, SUSPENDING, SUSPENDED, and TERMINATED.
zone string	URL of the zone where the instance resides.
machineType string	URL of the machine type resource used by this instance.
cpuPlatform string	The CPU platform used by this instance.
creationTimestamp string	Creation timestamp in RFC3339 text format.
deletionProtection string	Whether the resource should be protected against deletion.
disks Array[Disk]	Array of disks associated with this instance.
kind string	Type of the resource.
labelFingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
metadata object	The metadata key/value pairs assigned to this instance.
networkInterfaces Array[object]	An array of network configurations for this instance.
scheduling object	Sets the scheduling options for this instance.
selfLink string	Server-defined URL for this resource.
startRestricted boolean	Whether a VM has been restricted for start because Compute Engine has detected suspicious activity.
tags object	Tags to apply to this instance. Tags are used to identify valid sources or targets for network firewalls and are specified by the client during instance creation.
shortMachineType string	A short version of the machineType name.
project string	The project where the instance resides.
internalIp string	The instance's internal IP.
shortNetwork string	The network to which the instance is connected to.
shortSubnetwork string	The sub-network within the network the instance is connected to.
iconUrl string	Icon representing the OS installed on the instance's boot disk.
osImageName string	The name of the OS image installed on the instance's boot disk.
osImageSelfLink string	The full URL to the OS image.
osImageSizeInGb string	The size of the OS image.
bootDiskSizeInGb string	The size of the instance's boot disk.
cpuCount string	The number of vCPUs for the machine type.
memoryInGB string	The memory size for the machine name.
id UUID	The id of the instance.
name string	The display name of the instance.
shortZone string	A short version of the zone name.
shortRegion string	A short version of the region name.

Retrieve an instance

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/5611478403377505138"

The above command returns a JSON structured like this:

{
  "data": {
    "status": "RUNNING",
    "zone": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
    "machineType": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/machinetypes/f1-micro",
    "cpuPlatform": "Intel Skylake",
    "creationTimestamp": "2019-04-19T12:12:30.756-07:00",
    "deletionProtection": false,
    "disks": [
      {
        "autoDelete": true,
        "boot": true,
        "deviceName": "i-test-kkn",
        "guestOsFeatures": [
          {
            "type": "VIRTIO_SCSI_MULTIQUEUE"
          }
        ],
        "index": 0,
        "interface": "SCSI",
        "kind": "compute#attachedDisk",
        "licenses": [
          "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
        ],
        "mode": "READ_WRITE",
        "source": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/disks/i-test-kkn",
        "type": "PERSISTENT"
      }
    ],
    "kind": "compute#instance",
    "labelFingerprint": "42WmSpB8rSM=",
    "metadata": {
      "fingerprint": "WFshDDge4fM=",
      "items": [
        {
          "key": "startup-script",
          "value": "#! /bin/bash\napt-get update\nEOF"
        }
      ],
      "kind": "compute#metadata"
    },
    "networkInterfaces": [
      {
        "accessConfigs": [
          {
            "kind": "compute#accessConfig",
            "name": "external-nat",
            "natIP": "35.203.99.102",
            "networkTier": "PREMIUM",
            "type": "ONE_TO_ONE_NAT"
          }
        ],
        "fingerprint": "NG6-4Cdf0KA=",
        "kind": "compute#networkInterface",
        "name": "nic0",
        "network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
        "networkIP": "10.162.0.7",
        "subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default"
      }
    ],
    "scheduling": {
      "automaticRestart": true,
      "onHostMaintenance": "MIGRATE",
      "preemptible": false
    },
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a/instances/i-test-kkn",
    "startRestricted": false,
    "tags": {
      "fingerprint": "42WmSpB8rSM="
    },
    "shortMachineType": "custom-2-2048",
    "project": "test-area-oox",
    "internalIp": "10.162.0.7",
    "externalIp": "35.203.99.102",
    "shortNetwork": "default",
    "shortSubnetwork": "default",
    "iconUrl": "/rest/services/assets/gcp/os_logo/debian.png",
    "osImageName": "debian-9-stretch",
    "osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
    "osImageSizeInGb": 0,
    "bootDiskSizeInGb": 0,
    "cpuCount": 2,
    "memoryInGB": 2.000000,
    "id": "5611478403377505138",
    "name": "i-test-kkn",
    "shortZone": "northamerica-northeast1-a",
    "shortRegion": "northamerica-northeast1"
  }
}

GET /services/:service_code/:environment_name/instances/:id

Retrieve an instance in a given environment.

Attributes
status string	The status of the instance. One of the following values: PROVISIONING, STAGING, RUNNING, STOPPING, STOPPED, SUSPENDING, SUSPENDED, and TERMINATED.
zone string	URL of the zone where the instance resides.
machineType string	URL of the machine type resource used by this instance.
cpuPlatform string	The CPU platform used by this instance.
creationTimestamp string	Creation timestamp in RFC3339 text format.
deletionProtection string	Whether the resource should be protected against deletion.
disks Array[Disk]	Array of disks associated with this instance.
kind string	Type of the resource.
labelFingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
metadata object	The metadata key/value pairs assigned to this instance.
networkInterfaces Array[object]	An array of network configurations for this instance.
scheduling object	Sets the scheduling options for this instance.
selfLink string	Server-defined URL for this resource.
startRestricted boolean	Whether a VM has been restricted for start because Compute Engine has detected suspicious activity.
tags object	Tags to apply to this instance. Tags are used to identify valid sources or targets for network firewalls and are specified by the client during instance creation.
shortMachineType string	A short version of the machineType name.
project string	The project where the instance resides.
internalIp string	The instance's internal IP.
shortNetwork string	The network to which the instance is connected to.
shortSubnetwork string	The sub-network within the network the instance is connected to.
iconUrl string	Icon representing the OS installed on the instance's boot disk.
osImageName string	The name of the OS image installed on the instance's boot disk.
osImageSelfLink string	The full URL to the OS image.
osImageSizeInGb string	The size of the OS image.
bootDiskSizeInGb string	The size of the instance's boot disk.
cpuCount string	The number of vCPUs for the machine type.
memoryInGB string	The memory size for the machine name.
id UUID	The id of the instance.
name string	The display name of the instance.
shortZone string	A short version of the zone name.
shortRegion string	A short version of the region name.

Create an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances"

Request body examples:

// Create an instance with an existing IP
{
  "name": "my-instance",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-a",
  "bootDiskType": "pd-standard",
  "bootDiskSizeInGb": "10",
  "cpuCount": "2",
  "memoryInGB": "4.5",
  "osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
  "shortSubnetwork": "production-net",
  "shortIP": "my-ip-name",
  "startupScript": "#! /bin/bash\napt-get update\nEOF"
}

// Create an instance with a new static IP
{
  "name": "my-instance",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-a",
  "bootDiskType": "pd-standard",
  "bootDiskSizeInGb": "10",
  "cpuCount": "2",
  "memoryInGB": "4.5",
  "osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
  "shortSubnetwork": "staging-net",
  "reserveStaticIP": true
}

// Create an instance with an ephemeral IP
{
  "name": "my-instance",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-a",
  "bootDiskType": "pd-standard",
  "bootDiskSizeInGb": "10",
  "cpuCount": "2",
  "memoryInGB": "4.5",
  "osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
  "shortSubnetwork": "development-net",
  "ephemeralIP": true
}

// Create an instance with no external IP
{
  "name": "my-instance",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-a",
  "bootDiskType": "pd-standard",
  "bootDiskSizeInGb": "10",
  "cpuCount": "2",
  "memoryInGB": "4.5",
  "osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
  "shortSubnetwork": "demo-net",
}

POST /services/:service_code/:environment_name/instances

Create a new instance.

Required
name string	The display name of the instance.
shortRegion string	A short version of the region name.
shortZone string	A short version of the zone name.
bootDiskType string	The boot disk type. Choices are 'pd-standard' or 'pd-ssd'.
bootDiskSizeInGb string	The size of the boot disk in GB. Acceptable values are 1 to 2000, inclusive.
cpuCount string	Updated number of vCPUs of instance.
memoryInGB string	Updated memory of instance.
osImageSelfLink string	The full URL to the OS image.
shortSubnetwork string	The subnet that the instance is attached to upon creation. (Note that the subnet must be in the same region as the instance).

Optional
reserveStaticIP boolean	If the value is true, a new static IP would be reserved and provided to the resource.
shortIP string	The name of an existing regional external IP address assigned to this instance in the same region. This argument is only valid in conjunction with reserveStaticIP and ephemeral IP being false.
ephemeralIP boolean	If the value is false, reserve static IP is false and if no shortIP is provided the instance won't have an external IP. If the value is true, an ephemeral external IP address will be assigned.
startupScript string	A startup script metadata item to run every time the instance boots up.

Delete an instance

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/5611478403377505138"

Request body example:

{
   "deleteSnapshots": true,
}

DELETE /services/:service_code/:environment_name/instances/:id

Delete an existing instance.

Optional
deleteSnapshots boolean	Whether captured snapshops of associated auto-deletable disks should be deleted

Change machine type

A machine type determines the number of vCPUs and the size of the memory allocated to new instances.

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/6564997542943928188?operation=resize"

Request body example:

{
  "cpuCount": "2",
  "memoryInGB": "4.5"
}

POST /services/:service_code/:environment_name/instances/:id?operation=resize

Update the number of vCPUs and memory of an existing instance.

Optional
cpuCount string	Updated number of vCPUs of instance.
memoryInGB string	Updated memory of instance.

Change external IP

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/6564997542943928188?operation=change_external_ip"

Request body examples:

// Changing the IP to an ephemeral IP, just leave it empty
{ }

// Changing the IP to a new static IP
{
  "reserveStaticIP" : true
}

// Changing the IP to an existing IP
{
  "shortIP" : "your-ip-name"
}

POST /services/:service_code/:environment_name/instances/:id?operation=change_external_ip

Change the static external IP of an existing instance.

Optional
shortIP String	The name of a static external IP in the same region as the instance.
reserveStaticIP boolean	Specify to reserve a new external IP for the instance. Cannot be specified when 'shortIP' is also specified.

Get SSH command

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/6564997542943928188?operation=get_ssh"

Request body example:

{
  "sshKeyId": "my-ssh-key"
}

POST /services/:service_code/:environment_name/instances/:id?operation=get_ssh

Retrieve a command to allow you to SSH into a give running instance.

Required
sshKeyId string	The id of an existing SSH key already save in the environment. Mutually exclusive with publicKey.
publicKey string	The SSH key text. Mutually exclusive with sshKeyId. A new SSH key will be save in the environment.

Set Windows password

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/6564997542943928188?operation=set_windows_password"

Request body example:

{
    "username": "my-user"
}

POST /services/:service_code/:environment_name/instances/:id?operation=set_windows_password

Set and retrieve a generated password to a given user on a running Windows instance.

Required
username string	The username.

Manage group membership

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/2986056884972096897?operation=manage_group_membership"

Request body example:

{
    "shortGroups": ["my-group"]
}

POST /services/:service_code/:environment_name/instancegroups/:id?operation=manage_group_membership

Manage an instance's membership to groups.

Required
shortGroups array[string]	Array of group names representing the current groups the instance belongs to. If a group, which the instance currently belongs to, is not kept in the list, the instance will be removed from the group. If the array is empty, the instance will be removed from all the groups it currently belongs to.

Start an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/6564997542943928188?operation=start"

POST /services/:service_code/:environment_name/instances/:id?operation=start

Start an existing instance. The instance must be in the TERMINATED status for this operation to work.

Stop an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/6564997542943928188?operation=stop"

POST /services/:service_code/:environment_name/instances/:id?operation=stop

Stop an existing instance. The instance must be in either the RUNNING or STOPPING status for this operation to work. The default behavior is that the instance (denote by id) will be stopped gracefully.

Edit a startup script

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instances/6564997542943928188?operation=edit_startup_script"

Request body example:

{
    "startupScript": "#! /bin/bash\ncat <<EOF > /var/www/html/index.html\n<html><body><h1>Hello World</h1>\n<p>This page was created from a simple startup script!</p>\n</body></html>\nEOF"
}

POST /services/:service_code/:environment_name/instances/:id?operation=edit_startup_script

Edit the startup script for an existing instance.

Required
startupScript string	A startup script metadata item to run every time the instance boots up.

Instance groups

An instance group is a collection of VM instances that you can manage as a single entity. Instance groups are used to apply load balancing to groups of heterogeneous instances. In a load balancer setup, an instance group can be used as part of a backend service.

List instance groups

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instancegroups"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "creationTimestamp": "2019-09-06T12:28:47.389-07:00",
      "description": "",
      "fingerprint": "42WmSpB8rSM=",
      "kind": "compute#instanceGroup",
      "namedPorts": [
        {
          "name": "http",
          "port": 80
        }
      ],
      "network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a/instanceGroups/ig-test-vmd",
      "size": 0,
      "subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/subnetworks/default",
      "zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a",
      "id": "2986056884972096897",
      "name": "ig-test-vmd",
      "shortZone": "us-central1-a",
      "shortRegion": "us-central1"
    }
  ],
    "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/instancegroups

Retrieve a list of all instance groups in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
fingerprint string	A short sequence of bytes used to identify the named ports.
id UUID	The id of the instance group.
kind string	Type of the resource.
name string	The display name of the instance group.
namedPorts object	Assigns a name to a port number. This allows the system to reference ports by the assigned name instead of a port number. Named ports apply to all instances in this instance group.
network string	The network to which the instance group is connected to.
selfLink string	Server-defined URL for this resource.
shortRegion string	A short version of the region name.
shortZone string	A short version of the zone name.
size integer	The number of instances in the group.
subnetwork string	The sub-network within the network the instance group is connected to.
zone string	URL of the zone where the instance group resides.

Retrieve an instance group

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instancegroups/2986056884972096897"

The above command returns a JSON structured like this:

{
  "data": {
    "creationTimestamp": "2019-09-06T12:28:47.389-07:00",
    "description": "",
    "fingerprint": "42WmSpB8rSM=",
    "kind": "compute#instanceGroup",
    "namedPorts": [
      {
        "name": "http",
        "port": 80
      }
    ],
    "network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a/instanceGroups/ig-test-vmd",
    "size": 0,
    "subnetwork": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/subnetworks/default",
    "zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/us-central1-a",
    "id": "2986056884972096897",
    "name": "ig-test-vmd",
    "shortZone": "us-central1-a",
    "shortRegion": "us-central1"
  }
}

GET /services/:service_code/:environment_name/instancegroups/:id

Retrieve an instance group in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
fingerprint string	A short sequence of bytes used to identify the named ports.
id UUID	The id of the instance group.
kind string	Type of the resource.
name string	The display name of the instance group.
namedPorts object	Assigns a name to a port number. This allows the system to reference ports by the assigned name instead of a port number. Named ports apply to all instances in this instance group.
network string	The network to which the instance group is connected to.
selfLink string	Server-defined URL for this resource.
shortRegion string	A short version of the region name.
shortZone string	A short version of the zone name.
size integer	The number of instances in the group.
subnetwork string	The sub-network within the network the instance group is connected to.
zone string	URL of the zone where the instance group resides.

Create an instance group

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instancegroups"

Request body example:

{
  "name": "my-group",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-b",
  "shortNetwork": "default",
  "shortSubnetwork": "default",
  "shortInstances": ["instance-1"]
}

POST /services/:service_code/:environment_name/instancegroups

Create a new instance group.

Required
name string	The display name of the instance group.
shortZone string	A short version of the zone name.

Optional
shortInstances array[string]	Array of instance names to add to the instance group upon creation. All these instances should belong to the zone provided and should be in the same subnet.
shortNetwork string	The network to which the instance group is connected to.
shortRegion string	A short version of the region name.
shortSubnetwork string	The sub-network within the network the instance group is connected to. This will only be applied to the instance group if instances are being bound at creation time, if not, only the network will be applied to the instance group.

Delete an instance group

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instancegroups/2986056884972096897"

DELETE /services/:service_code/:environment_name/instancegroups/:id

Delete an existing instance group.

Manage instance members

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/instancegroups/2986056884972096897?operation=manage_instance_members"

Request body example:

{
    "shortInstances": ["instance-2"]
}

POST /services/:service_code/:environment_name/instancegroups/:id?operation=manage_instance_members

Manage instance members in an existing instance group.

Required
shortInstances array[string]	Array of instance names representing the current members of the instance group. If a current instance member is not kept in the list, it will be removed from the group. If the array is empty, all the instance members will be removed.

Disks

Deploy and manage your disks.

List disks

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "creationTimestamp": "2019-05-07T08:46:06.488-07:00",
      "sizeGb": "10",
      "zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a",
      "status": "ATTACHED",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/disks/d-test-dow",
      "type": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/diskTypes/pd-standard",
      "lastAttachTimestamp": "2019-05-07T08:46:11.989-07:00",
      "users": [
        "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/instances/i-test-aum"
      ],
      "labelFingerprint": "42WmSpB8rSM=",
      "physicalBlockSizeBytes": "4096",
      "kind": "compute#disk",
      "shortUsers": "i-test-aum",
      "shortType": "pd-standard",
      "attachMode": "READ_WRITE",
      "autoDelete": false,
      "id": "5333546534174463697",
      "name": "d-test-dow",
      "shortZone": "northamerica-northeast1-a",
      "shortRegion": "northamerica-northeast1"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/disks

Retrieve a list of all disks in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
sizeGb string	The size of the disk in GB. Acceptable values are 1 to 65536, inclusive.
zone string	URL of the zone where the instance resides.
status string	The status of the disk. One of the following values: READY, CREATING, ATTACHING, ATTACHED, DETACHING, RESIZING, DELETING, and DEPRECATED.
selfLink string	Server-defined URL for this resource.
type string	URL of the disk type resource describing which disk type to use to create the disk. Choices are ':url/pd-standard' or ':url/pd-ssd'.
lastAttachTimestamp string	Timestamp representing the last time the disk was attached.
users Array[string]	Links to the instances the disk is attached to.
labelFingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
physicalBlockSizeBytes string	Physical block size of the persistent disk, in bytes. Currently supported sizes are 4096 and 16384.
kind string	Type of the resource.
shortUsers string	The names of the instances the disk is attached to.
shortType string	The disk type. Choices are 'pd-standard' or 'pd-ssd'.
attach_mode string	The mode used to attach the disk to instances. Valid modes are READ_WRITE or READ_ONLY.
autoDelete boolean	Whether the resource should be deleted when the instance it's attached to are deleted.
id UUID	The id of the instance.
name string	The display name of the instance.
shortZone string	A short version of the zone name.
shortRegion string	A short version of the region name.

Retrieve a disk

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks/5333546534174463697"

The above command returns a JSON structured like this:

{
  "data": {
    "creationTimestamp": "2019-05-07T08:46:06.488-07:00",
    "sizeGb": "10",
    "zone": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a",
    "status": "ATTACHED",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/disks/d-test-dow",
    "type": "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/diskTypes/pd-standard",
    "lastAttachTimestamp": "2019-05-07T08:46:11.989-07:00",
    "users": [
      "https://www.googleapis.com/compute/v1/projects/test-area/zones/northamerica-northeast1-a/instances/i-test-aum"
      ],
    "labelFingerprint": "42WmSpB8rSM=",
    "physicalBlockSizeBytes": "4096",
    "kind": "compute#disk",
    "shortUsers": "i-test-aum",
    "shortType": "pd-standard",
    "attachMode": "READ_WRITE",
    "autoDelete": false,
    "id": "5333546534174463697",
    "name": "d-test-dow",
    "shortZone": "northamerica-northeast1-a",
    "shortRegion": "northamerica-northeast1"
  }
}

GET /services/:service_code/:environment_name/disks/:id

Retrieve a disk in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
sizeGb string	The size of the disk in GB. Acceptable values are 1 to 65536, inclusive.
zone string	URL of the zone where the instance resides.
status string	The status of the disk. One of the following values: READY, CREATING, ATTACHING, ATTACHED, DETACHING, RESIZING, DELETING, and DEPRECATED.
selfLink string	Server-defined URL for this resource.
type string	URL of the disk type resource describing which disk type to use to create the disk. Choices are ':url/pd-standard' or ':url/pd-ssd'.
lastAttachTimestamp string	Timestamp representing the last time the disk was attached.
users Array[string]	Links to the instances the disk is attached to.
labelFingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
physicalBlockSizeBytes string	Physical block size of the persistent disk, in bytes. Currently supported sizes are 4096 and 16384.
kind string	Type of the resource.
shortUsers string	The names of the instances the disk is attached to.
shortType string	The disk type. Choices are 'pd-standard' or 'pd-ssd'.
attachMode string	The mode used to attach the disk to instances. Valid modes are READ_WRITE or READ_ONLY.
autoDelete boolean	Whether the resource should be deleted when the instance it's attached to are deleted.
id UUID	The id of the instance.
name string	The display name of the instance.
shortZone string	A short version of the zone name.
shortRegion string	A short version of the region name.

Create a disk

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks"

Request body example:

{
  "name": "my-disk",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-a",
  "shortType": "pd-standard",
  "sizeGb": "10"
}

POST /services/:service_code/:environment_name/disks

Create a new disk

Required
name string	The display name of the instance.
shortRegion string	A short version of the region name.
shortZone string	A short version of the zone name.
shortType string	The disk type. Choices are 'pd-standard' or 'pd-ssd'.
sizeGb string	The size of the disk in GB. Acceptable values are 1 to 65536, inclusive.

Optional
physicalBlockSizeBytes string	Physical block size of the persistent disk, in bytes. Currently supported sizes are 4096 and 16384. Defaults to 4096.

Delete a disk

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks/5333546534174463697"

Request body example:

{
   "deleteSnapshots": true,
}

DELETE /services/:service_code/:environment_name/disks/:id

Destroy an existing disk. A disk can only be deleted if it's not attached to an instance.

Optional
deleteSnapshots boolean	Whether captured snapshops should be deleted

Attach a disk to an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks/5333546534174463697?operation=attach"

Request body example:

{
   "shortUsers": "5611478403377505138",
   "attachMode": "READ_WRITE",
   "autoDelete": false
}

POST /services/:service_code/:environment_name/disks/:id?operation=attach

Attach an existing disk to an instance.

Required
shortUsers string	The id of the instance to which the created disk should be attached
attachMode string	The mode used to attach the disk to the instance. Valid modes are READ_WRITE or READ_ONLY.
autoDelete boolean	Whether the resource should be deleted when the instance it's attached to are deleted. If attachMode is READ_ONLY, autoDelete has to be false.

Detach a disk from an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks/5333546534174463697?operation=detach"

Request body example:

{
   "shortUsers": "5611478403377505138"
}

POST /services/:service_code/:environment_name/disks/:id?operation=detach

Detach an existing disk from a given instance.

Required
shortUsers string	The id of the instance to which the created disk should be attached.

Resize a disk

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks/5333546534174463697?operation=resize"

Request body example:

{
   "sizeGb": "50"
}

POST /services/:service_code/:environment_name/disks/:id?operation=resize

Resize an existing disk.

Required
sizeGb string	The size of the disk in GB. Valid values are 1 to 65536, inclusive, unless this is an instance's boot disk, then the valid values are 1 to 2000.

Take a snapshot of a disk

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/disks/5333546534174463697?operation=snapshot"

Request body example:

{
   "snapshotName": "my-snapshot"
}

POST /services/:service_code/:environment_name/disks/:id?operation=snapshot

Take a snapshot of a persistent disk.

Optional
snapshotName string	The name of the snapshot. A default value set if a snapshot name is not provided.

SSH keys

SSH keys are managed at the environment level.

List SSH keys

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sshkeys"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "user1",
      "name": "user1",
      "publicKey": "ssh-rsa mypublickey user1@host.com"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/sshkeys

Retrieve a list of all SSH keys in an environment.

Attributes
id string	The SSH key's id.
name string	The name of the SSH key.
publicKey string	A string representing the protocol, public key and username. GCP SSH keys documentation

Retrieve an SSH key

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sshkeys/user1"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "user1",
    "name": "user1",
    "publicKey": "ssh-rsa mypublickey user1@host.com"
  }
}

GET /services/:service_code/:environment_name/sshkeys/:id

Retrieve information about an SSH key of an environment.

Attributes
id string	The SSH key's id.
name string	The name of the SSH key.
publicKey string	A string representing the protocol, public key and username. GCP SSH keys documentation

Add an SSH key

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sshkeys"

Request body example:

{
  "name": "user1",
  "publicKey": "ssh-rsa mypublickey user1@host.com"
}

POST /services/:service_code/:environment_name/sshkeys

Add an SSH key to the environment.

Attributes
name string	The name of the SSH key.
publicKey string	A string representing the protocol, public key and username. GCP SSH keys documentation

Delete an SSH key

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sshkeys/user1"

DELETE /services/:service_code/:environment_name/sshkeys/:name

Delete an existing SSH key from the environment.

Health checks

Health checking mechanisms determine whether VM instances respond properly to traffic.

List health checks

curl -X GET \
  -H 'MC-Api-key: your_api_key'
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/healthchecks"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "checkIntervalSec": 10,
      "creationTimestamp": "2019-09-18T12:39:48.982-07:00",
      "description": "",
      "healthyThreshold": 2,
      "id": "5930212998788364011",
      "kind": "compute#healthCheck",
      "name": "hc-name-xxx",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/healthChecks/healthcheckname",
      "httpHealthCheck": {
        "host": "",
        "port": 80,
        "portName": "http",
        "proxyHeader": "NONE",
        "requestPath": "/"
      },
      "timeoutSec": 5,
      "type": "HTTP",
      "unhealthyThreshold": 3,
      "portNumber": "80"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /service/:service_code/:environment_name/healthchecks

Retrieve a list of all health checks.

Attributes
checkIntervalSec int	How often (in seconds) to send a health check. The default value is 5 seconds.
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource. Provide this property when you create the resource.
healthyThreshold	A so-far unhealthy instance will be marked healthy after this many consecutive successes. The default value is 2.
httpHealthCheck object	When the type is set to HTTP, this object represents the health check.
httpSHealthCheck object	When the type is set to HTTPS, this object represents the health check.
id string	The unique identifier for the resource. This identifier is defined by the server.
kind string	Type of the resource.
name string	Name of the resource. Provided by the client when the resource is created.
selfLink string	Server-defined URL for this resource.
timeoutSec int	How long (in seconds) to wait before claiming failure. The default value is 5 seconds. It is invalid for timeoutSec to have greater value than checkIntervalSec.
type string	Specifies the type of the health check, either HTTP or HTTPS. If not specified, the default is HTTP. Exactly one of the protocol-specific health check field must be specified, which must match type field.
unhealthyThreshold int	A so-far healthy instance will be marked unhealthy after this many consecutive failures. The default value is 2.
portNumber string	The port number for health check.

Retrieve a health check

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/healthchecks/5930212998788364011"

The above command returns a JSON structured like this:

{
  "data": {
    "checkIntervalSec": 10,
    "creationTimestamp": "2019-09-18T12:39:48.982-07:00",
    "description": "",
    "healthyThreshold": 2,
    "id": "5930212998788364011",
    "kind": "compute#healthCheck",
    "name": "hc-name-xxx",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/healthChecks/firsthealthcheck",
    "httpHealthCheck": {
        "host": "",
        "port": 80,
        "portName": "http",
        "proxyHeader": "NONE",
        "requestPath": "/"
      },
    "timeoutSec": 5,
    "type": "HTTP",
    "unhealthyThreshold": 3,
    "portNumber": "80"
  }
}

GET /services/:service_code/:environment_name/healthchecks/:id

Retrieve a health check in a given environment.

Attributes
checkIntervalSec int	How often (in seconds) to send a health check. The default value is 5 seconds.
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource. Provide this property when you create the resource.
healthyThreshold int	A so-far unhealthy instance will be marked healthy after this many consecutive successes. The default value is 2.
httpHealthCheck object	When the type is set to HTTP, this object represents the health check.
httpSHealthCheck object	When the type is set to HTTPS, this object represents the health check.
id string	The unique identifier for the resource. This identifier is defined by the server.
kind string	Type of the resource.
name string	Name of the resource. Provided by the client when the resource is created.
selfLink string	Server-defined URL for this resource.
timeoutSec int	How long (in seconds) to wait before claiming failure. The default value is 5 seconds. It is invalid for timeoutSec to have greater value than checkIntervalSec.
type string	Specifies the type of the health check, either HTTP or HTTPS. If not specified, the default is HTTP. Exactly one of the protocol-specific health check field must be specified, which must match type field.
unhealthyThreshold int	A so-far healthy instance will be marked unhealthy after this many consecutive failures. The default value is 2.
portNumber string	The port number for health check.

Create a health check

curl -X POST \
  -H 'MC-Api-Key: your_api_key' \
  -H "Content-Type: application/json" \
  -d "request _body" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/healthchecks"

POST /services/:service_code/:environment_name/healthchecks

Create a new health check

Required
name string	The display name of the health check.

Optional
type string	Specifies the type of the health check, either HTTP or HTTPS. If not specified, the default is HTTP.
portNumber string	The port number for the health check. The default is 80 for HTTP, 443 for HTTPS.
description string	Description of the health check.

Delete a health check

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/healthchecks/6938691570659391640"

DELETE /services/:service_code/:environment_name/healthchecks/:id

Destroy an existing health check. A health check can only be deleted if it's not used by a backend service.

Edit a health check

curl -X PUT \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/healthchecks/6938691570659391640"

Request body example:

{
  "portNumber": 80,
  "type": "HTTP",
  "description": "it is for test"
}

PUT /services/:service_code/:environment_name/healthchecks/:id

Edit an existing health check.

Required
portNumber integer	The port number of the health check.

Optional
type string	Specifies the type of the health check, either HTTP or HTTPS. The type should be valided (If not specified, the default is HTTP).
description string	Description of the health check.

Snapshots

Snapshots can be created to periodically back up data from your instances.

List snapshots

curl -X GET \
  -H 'MC-Api-key: your_api_key'
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/snapshots"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "description": "This is a snapshot description",
      "creationTimestamp": "2020-06-17T08:02:34.132-07:00",
      "status": "READY",
      "sourceDisk": "https://www.googleapis.com/compute/v1/projects/testarea/zones/northamerica-northeast1-a/disks/source-instance-name",
      "sourceDiskId": "7481902077681239049",
      "diskSizeGb": "10",
      "storageBytes": "932828192",
      "storageBytesStatus": "UP_TO_DATE",
      "licenses": [
        "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
      ],
      "selfLink": "https://www.googleapis.com/compute/v1/projects/testarea/global/snapshots/snapshot-1",
      "labels": {
        "sampleLabel": "label value"
      },
      "labelFingerprint": "6gSwJq6EkEI=",
      "licenseCodes": [
        "1023205"
      ],
      "storageLocations": [
        "us"
      ],
      "kind": "compute#snapshot",
      "downloadBytes": "932822788",
      "id": "7059283128121212212",
      "name": "snapshot-1"
    },
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /service/:service_code/:environment_name/snapshots

Retrieve a list of all snapshots.

Attributes
description string	The snapshot description.
creationTimestamp string	Creation timestamp in RFC3339 text format.
status string	The status of the snapshot. One of the following values: CREATING, DELETING, FAILED, READY, or UPLOADING.
sourceDisk string	The source disk used to create this snapshot.
sourceDiskId string	The ID value of the disk used to create this snapshot.
diskSizeGb string	Size of the source disk, specified in GB.
storageBytes string	A size of the storage used by the snapshot.
storageBytesStatus string	An indicator whether storageBytes is in a stable state or it is being adjusted as a result of shared storage reallocation. This status can either be UPDATING, meaning the size of the snapshot is being updated, or UP_TO_DATE, meaning the size of the snapshot is up-to-date.
licenses Array[string]	A list of public visible licenses that apply to this snapshot.
selfLink string	Server-defined URL for the resource.
labels Object	Mapped object containing labels applied to this snapshot. Label values may be empty.
labelFingerprint string	A fingerprint for the labels being applied to this snapshot. Initially generated by Compute Engine and changes after every request to modify or update labels.
licenseCodes Array[string]	Integer license codes indicating which licenses are attached to this snapshot.
storageLocations Array[string]	Cloud Storage bucket storage location of the snapshot (regional or multi-regional).
kind string	Type of the resource. Always compute#snapshot for Snapshot resources.
downloadBytes string	Number of bytes downloaded to restore a snapshot to a disk.
id string	The unique identifier for the resource. This identifier is defined by the server.
name string	Name of the resource; provided by the client when the resource is created.

Retrieve a snapshot

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/snapshots/7059283128121212212"

The above command returns a JSON structured like this:

{
  "data": {
      "description": "This is a snapshot description",
      "creationTimestamp": "2020-06-17T08:02:34.132-07:00",
      "status": "READY",
      "sourceDisk": "https://www.googleapis.com/compute/v1/projects/testarea/zones/northamerica-northeast1-a/disks/source-instance-name",
      "sourceDiskId": "7481902077681239049",
      "diskSizeGb": "10",
      "storageBytes": "932828192",
      "storageBytesStatus": "UP_TO_DATE",
      "licenses": [
        "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
      ],
      "selfLink": "https://www.googleapis.com/compute/v1/projects/testarea/global/snapshots/snapshot-1",
      "labels": {
        "sampleLabel": "label value"
      },
      "labelFingerprint": "6gSwJq6EkEI=",
      "licenseCodes": [
        "1023205"
      ],
      "storageLocations": [
        "us"
      ],
      "kind": "compute#snapshot",
      "downloadBytes": "932822788",
      "id": "7059283128121212212",
      "name": "snapshot-1"
  }
}

GET /services/:service_code/:environment_name/snapshots/:id

Retrieve a specific snapshot by id.

Attributes
description string	The snapshot description.
creationTimestamp string	Creation timestamp in RFC3339 text format.
status string	The status of the snapshot. One of the following values: CREATING, DELETING, FAILED, READY, or UPLOADING.
sourceDisk string	The source disk used to create this snapshot.
sourceDiskId string	The ID value of the disk used to create this snapshot.
diskSizeGb string	Size of the source disk, specified in GB.
storageBytes string	A size of the storage used by the snapshot.
storageBytesStatus string	An indicator whether storageBytes is in a stable state or it is being adjusted as a result of shared storage reallocation. This status can either be UPDATING, meaning the size of the snapshot is being updated, or UP_TO_DATE, meaning the size of the snapshot is up-to-date.
licenses Array[string]	A list of public visible licenses that apply to this snapshot.
selfLink string	Server-defined URL for the resource.
labels Object	Mapped object containing labels applied to this snapshot. Label values may be empty.
labelFingerprint string	A fingerprint for the labels being applied to this snapshot. Initially generated by Compute Engine and changes after every request to modify or update labels.
licenseCodes Array[string]	Integer license codes indicating which licenses are attached to this snapshot.
storageLocations Array[string]	Cloud Storage bucket storage location of the snapshot (regional or multi-regional).
kind string	Type of the resource. Always compute#snapshot for Snapshot resources.
downloadBytes string	Number of bytes downloaded to restore a snapshot to a disk.
id string	The unique identifier for the resource. This identifier is defined by the server.
name string	Name of the resource; provided by the client when the resource is created.

Create a snapshot

See take a snapshot of a disk to create a snapshot.

Delete a snapshot

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/snapshots/463325715266630842"

DELETE /services/:service_code/:environment_name/snapshots/:id

Destroy an existing snapshot. A snapshot can only be deleted if it is in READY state.

Networking

Networks

A network is an isolated network where you can place groups of resources, such as instances.

List networks

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/networks"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "autoCreateSubnetworks": true,
      "creationTimestamp": "2019-03-12T07:09:22.374-07:00",
      "description": "Default network for the project",
      "id": "6402509859159933821",
      "name": "default",
      "kind": "compute#network",
      "routingConfig": {
        "routingMode": "REGIONAL"
      },
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
      "subnetworks": [
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west2/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east4/subnetworks/default"
      ],
      "numberSubnets": 2,
      "mode": "custom"
    },
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/networks

Retrieve a list of all networks in an environment.

Attributes
autoCreateSubnetworks boolean	When set to true, the VPC network is created in "auto" mode. When set to false, the VPC network is created in "custom" mode.
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
id string	The network's id.
name string	The network's name.
kind string	Type of the resource.
routingConfig object	The network-level routing configuration for this network. Used by Cloud Router to determine what type of network-wide routing behavior to enforce. RoutingMode is either REGIONAL or GLOBAL.
selfLink string	Server-defined URL for this resource.
subnetworks Array[URL]	Server-defined fully-qualified URLs for all subnetworks in this VPC network.
numberSubnets integer	Number of subnets in the network.
mode string	If autoCreateSubnetworks is true, then auto, else custom.

Retrieve a network

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/gcp/test-area/networks/6402509859159933821"

The above command returns a JSON structured like this:

{
   "data": {
      "autoCreateSubnetworks": true,
      "creationTimestamp": "2019-03-12T07:09:22.374-07:00",
      "description": "Default network for the project",
      "id": "6402509859159933821",
      "name": "default",
      "kind": "compute#network",
      "routingConfig": {
        "routingMode": "REGIONAL"
      },
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
      "subnetworks": [
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west2/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-west1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1/subnetworks/default",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-east4/subnetworks/default"
      ],
      "numberSubnets": 2,
      "mode": "custom"
    }
}

GET /services/:service_code/:environment_name/networks/:id

Retrieve information about a network.

Attributes
autoCreateSubnetworks boolean	When set to true, the VPC network is created in "auto" mode. When set to false, the VPC network is created in "custom" mode.
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
id string	The network's id.
name string	The network's name.
kind string	Type of the resource.
routingConfig object	The network-level routing configuration for this network. Used by Cloud Router to determine what type of network-wide routing behavior to enforce. RoutingMode is either REGIONAL or GLOBAL.
selfLink string	Server-defined URL for this resource.
subnetworks Array[URL]	Server-defined fully-qualified URLs for all subnetworks in this VPC network.
numberSubnets integer	Number of subnets in the network.
mode string	If autoCreateSubnetworks is true, then auto, else custom.

Create a network

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/networks"

Request body example for network in auto subnet creation mode:

{
    "name": "vpc-name",
    "autoCreateSubnetworks": true
}

Request body example for network in custom subnet creation mode:

{
    "name": "vpc-name",
    "subnetName": "subnet-name",
    "subnetShortRegion": "northamerica-northeast1",
    "subnetIpCidrRange": "10.0.0.0/20"
}

POST /services/:service_code/:environment_name/networks

Create a new network and attach subnet

Required in auto mode
name string	The display name of the network.
autoCreateSubnetworks boolean	Whether subnets will be automatically created for each region.

Required in custom mode
name string	The display name of the network.
subnetName string	The display name of the subnet.
subnetShortRegion string	A short version of the region name of the subnet.
subnetIpCidrRange string	The CIDR IP range of the subnet.

Optional
description string	Description of the network.

Delete a network

curl -X DELETE \
  -H "mc-api-key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/networks/6402509859159933821"

DELETE /services/:service_code/:environment_name/networks/:id

Delete an existing network.

Firewall rules

Firewall allows you to control inbound and outbound traffic to your environment.

List firewall rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/firewallrules"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "allowed": [
        {
          "IPProtocol": "tcp",
          "ports": [
            "80"
          ]
        }
      ],
      "creationTimestamp": "2019-03-13T13:28:49.840-07:00",
      "description": "",
      "direction": "INGRESS",
      "disabled": false,
      "id": "4890726785951782638",
      "kind": "compute#firewall",
      "logConfig": {
        "enable": false
      },
      "name": "default-allow-http",
      "network": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/networks/default",
      "priority": 1000,
      "selfLink": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/firewalls/default-allow-http",
      "sourceRanges": [
        "0.0.0.0/0"
      ],
      "targetTags": [
        "http-server"
      ],
      "details": "tcp : 80",
      "action": "allow"
    }
  ],
  "metadata": {
    "recordCount": 7
  }
}

GET /services/:service_code/:environment_name/firewallrules

Retrieve a list of all firewall rules in a given environment.

Attributes
allowed Array[object]	The list of ALLOW rules specified by this firewall.
creationTimestamp string	Creation timestamp in RFC3339 text format.
denied Array[object]	The list of DENY rules specified by this firewall.
description string	An optional description of this firewall rule.
direction string	Direction of traffic to which this firewall applies, either INGRESS or EGRESS. The default is INGRESS.
disabled boolean	Denotes whether the firewall rule is disabled. When set to true, the firewall rule is not enforced and the network behaves as if it did not exist.
id string	The unique identifier for the resource.
kind string	Type of the resource.
logConfig object	This field denotes the logging options for a particular firewall rule. If logging is enabled, logs will be exported to Stackdriver.
name string	The display name of the firewall rule.
network string	URL of the network resource for this firewall rule.
priority integer	Priority for this rule. This is an integer between 0 and 65535, both inclusive. The default value is 1000. Relative priorities determine which rule takes effect if multiple rules apply. Lower values indicate higher priority. For example, a rule with priority 0 has higher precedence than a rule with priority 1. DENY rules take precedence over ALLOW rules if they have equal priority. Note that VPC networks have implied rules with a priority of 65535. To avoid conflicts with the implied rules, use a priority number less than 65535.
selfLink string	Server-defined URL for this resource.
sourceRanges Array[string]	Server-defined URL for the resource.
targetTags Array[string]	A list of tags that controls which instances the firewall rule applies to. If targetTags are specified, then the firewall rule applies only to instances in the VPC network that have one of those tags. If no targetTags are specified, the firewall rule applies to all instances on the specified network.
details string	Concatenation of the IP protocols followed by the port ranges.
action string	The firewall rule type: 'allow' (allow traffic) or 'deny' (deny traffic).

Retrieve a firewall rule

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/firewallrules/4890726785951782638"

The above command returns a JSON structured like this:

{
  "data": {
    "allowed": [
    {
        "IPProtocol": "tcp",
        "ports": [
        "80"
        ]
    }
    ],
    "creationTimestamp": "2019-03-13T13:28:49.840-07:00",
    "description": "",
    "direction": "INGRESS",
    "disabled": false,
    "id": "4890726785951782638",
    "kind": "compute#firewall",
    "logConfig": {
    "enable": false
    },
    "name": "default-allow-http",
    "network": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/networks/default",
    "priority": 1000,
    "selfLink": "https://www.googleapis.com/compute/v1/projects/flo-cmc-gcp-cay/global/firewalls/default-allow-http",
    "sourceRanges": [
    "0.0.0.0/0"
    ],
    "targetTags": [
    "http-server"
    ],
    "details": "tcp : 80",
    "action": "allow"
  }
}

GET /services/:service_code/:environment_name/firewallrules/:id

Retrieve a firewall rules in a given environment.

Attributes
allowed Array[object]	The list of ALLOW rules specified by this firewall.
creationTimestamp string	Creation timestamp in RFC3339 text format.
denied Array[object]	The list of DENY rules specified by this firewall.
description string	An optional description of this firewall rule.
direction string	Direction of traffic to which this firewall applies, either INGRESS or EGRESS. The default is INGRESS.
disabled boolean	Denotes whether the firewall rule is disabled. When set to true, the firewall rule is not enforced and the network behaves as if it did not exist.
id string	The unique identifier for the resource.
kind string	Type of the resource.
logConfig object	This field denotes the logging options for a particular firewall rule. If logging is enabled, logs will be exported to Stackdriver.
name string	The display name of the firewall rule.
network string	URL of the network resource for this firewall rule.
priority integer	Priority for this rule. This is an integer between 0 and 65535, both inclusive. The default value is 1000. Relative priorities determine which rule takes effect if multiple rules apply. Lower values indicate higher priority. For example, a rule with priority 0 has higher precedence than a rule with priority 1. DENY rules take precedence over ALLOW rules if they have equal priority. Note that VPC networks have implied rules with a priority of 65535. To avoid conflicts with the implied rules, use a priority number less than 65535.
selfLink string	Server-defined URL for this resource.
sourceRanges Array[string]	Server-defined URL for the resource.
targetTags Array[string]	A list of tags that controls which instances the firewall rule applies to. If targetTags are specified, then the firewall rule applies only to instances in the VPC network that have one of those tags. If no targetTags are specified, the firewall rule applies to all instances on the specified network.
details string	Concatenation of the IP protocols followed by the port ranges.
action string	The firewall rule type: 'allow' (allow traffic) or 'deny' (deny traffic).

Create a firewall rule

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/firewallrule"

Request body example:

{
  "action": "allow",
  "all": true,
  "direction": "INGRESS",
  "name": "fw-rd-tuv",
  "priority": 1000,
  "range": "0.0.0.0/0",
}

POST /services/:service_code/:environment_name/firewallrule

Create a new firewall rule.

Required
action string	The firewall rule type: 'allow' (allow traffic) or 'deny' (deny traffic).
direction string	Direction of traffic to which this firewall applies, either INGRESS or EGRESS. The default is INGRESS.
name string	The display name of the firewall rule.
priority string	Priority for this rule. This is an integer between 0 and 65535, both inclusive. The default value is 1000.
range Array[string]	The source or destination range depending on the direction specified. The firewall rule applies only to traffic that has a source/destination IP address in these ranges. These ranges must be expressed in CIDR format.

Optional
all boolean	Specifies if the firewall rule is an allow all or deny all rule.
tcpPorts Array[string]	The tcp ports on which to apply the rule. These must be in the range [0, 65535).
udpPorts Array[string]	The udp ports on which to apply the rule. These must be in the range [0, 65535).
protocols Array[string]	Supported protocols are: icmp, esp, ah, sctp, ipip or a valid decimal IP protocol number.

Delete a firewall rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/firewallrule/4890726785951782638"

DELETE /services/:service_code/:environment_name/firewallrule/:id

Delete an existing firewall rule.

External IPs

External IP address to an instance or a forwarding rule if you need to communicate with the Internet, with resources in another network, or need to communicate with a resource outside of Compute Engine.

List external IPs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/externalips"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "address": "35.203.89.240",
      "prefixLength": 0,
      "status": "IN_USE",
      "region": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/zones/northamerica-northeast1-a",
      "users": [
        "https://www.googleapis.com/compute/v1/projects/test-env-qyu/zones/northamerica-northeast1-a/instances/i-root-fjt"
      ],
      "shortUsers": [
        "i-root-fjt"
      ],
      "shortRegion": "northamerica-northeast1",
      "type": "EPHEMERAL"
    },
    {
      "id": "5737719067147816064",
      "creationTimestamp": "2019-06-06T13:07:11.430-07:00",
      "name": "address1",
      "description": "",
      "address": "35.232.24.253",
      "prefixLength": 0,
      "status": "RESERVED",
      "region": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/us-central1",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/us-central1/addresses/address1",
      "networkTier": "PREMIUM",
      "addressType": "EXTERNAL",
      "kind": "compute#address",
      "shortRegion": "us-central1",
      "type": "STATIC"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/externalips

Retrieve a list of all external IPs in a given environment.

Attributes
id UUID	Unique identifier for this ressource. Only present for static IPs.
creationTimestamp string	Creation timestamp in RFC3339 text format.
name string	The display name of the address.
description string	An optional description of the address.
address string	The IP address.
prefixLength number	The prefix length if the resource reprensents an IP range.
status string	The status of the external IP address. One of the following: IN_USE, RESERVED, RESERVING.
region string	The URL of the region where the regional address resides.
selfLink string	Server-defined URL for this resource.
users Array[string]	Links to the instances the IP address is attached to.
networkTier *string	Network tier used to configure that address. One of PREMIUM or STANDARD. Defaulted to PREMIER.
addressType string	The type of address to reserve, either INTERNAL or EXTERNAL. We only list EXTERNAL addresses.
kind string	Type of the resource. Always compute#address for addresses.
shortUsers Array[string]	The names of the instances the IP address is attached to.
shortRegion string	A short version of the region name.
type string	One of EPHEMERAL or STATIC. EPHEMERAL are linked to an instance and are released automatically when an instance is deleted.

Retrieve a regional static IP address

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/externalips/8516891730356002156"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "8516891730356002156",
    "creationTimestamp": "2019-06-06T12:03:31.935-07:00",
    "name": "address1",
    "description": "",
    "address": "35.203.23.132",
    "prefixLength": 0,
    "status": "IN_USE",
    "region": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/northamerica-northeast1",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-env-qyu/regions/northamerica-northeast1/addresses/address1",
    "users": [
      "https://www.googleapis.com/compute/v1/projects/test-env-qyu/zones/northamerica-northeast1-a/instances/i-root-caf"
    ],
    "networkTier": "PREMIUM",
    "addressType": "EXTERNAL",
    "kind": "compute#address",
    "shortUsers": [
      "i-root-caf"
    ],
    "shortRegion": "northamerica-northeast1",
    "type": "STATIC"
  }
}

GET /services/:service_code/:environment_name/externalips/:id

Retrieve an external IP in a given environment. Only for static IPs.

Attributes
id UUID	Unique identifier for this ressource. Only present for static IPs.
creationTimestamp string	Creation timestamp in RFC3339 text format.
name string	The display name of the address.
description string	An optional description of the address.
address string	The IP address.
prefixLength number	The prefix length if the resource reprensents an IP range.
status string	The status of the external IP address. One of the following: IN_USE, RESERVED, RESERVING.
region string	The URL of the region where the regional address resides.
selfLink string	Server-defined URL for this resource.
users Array[string]	Links to the instances the IP address is attached to.
networkTier string	Network tier used to configure that address. One of PREMIUM or STANDARD. Defaulted to PREMIER.
addressType string	The type of address to reserve, either INTERNAL or EXTERNAL. We only list EXTERNAL addresses.
kind string	Type of the resource. Always compute#address for addresses.
shortUsers Array[string]	The names of the instances the IP address is attached to.
shortRegion string	A short version of the region name.
type string	One of EPHEMERAL or STATIC. EPHEMERAL are linked to an instance and are released automatically when an instance is deleted.

Reserve a regional external IP

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/externalips?operation=reserve"

Request body example:

{
  "name": "my-static-ip",
  "shortRegion": "northamerica-northeast1",
  "shortInstance": "my-instance-name"
}

POST /services/:service_code/:environment_name/externalips

Reserve a new external static IP in a given environment. If shortInstance is provided, the IP will be reserved and attached to this instance.

Required
name string	The display name of the external ip.
shortRegion string	A short version of the region name.

Optional
shortInstance string	The instance name to attach the new external ip address to.

Release a static IP address

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/externalips/8516891730356002156"

DELETE /services/:service_code/:environment_name/externalips/:id

Release an existing external IP. The external IP goes back to the reserved pool, and is available to be attached to another instance.

Routes

A route is a path that network traffic takes from an instance to other destinations. The destination can be inside a GCP network or outside.

List routes

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routes"

The above command returns a JSON structured like this:

{
  "data": [
    { "id": "6918030089270271318",
      "creationTimestamp": "2020-05-21T08:52:26.010-07:00",
      "name": "default-route-0f2f9d9f9910829a",
      "description": "Default local route to the subnetwork 10.172.0.0/20.",
      "network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
      "destRange": "10.172.0.0/20",
      "priority": 0,
      "nextHopNetwork": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/routes/default-route-0f2f9d9f9910829a",
      "kind": "compute#route",
      "networkName": "default"
    }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/routes

Retrieve a list of all routes in an environment.

Attributes
id string	The route's id.
creationTimestamp string	Creation timestamp in RFC3339 text format.
name string	The route's name.
description string	An optional description of this resource.
network string	URL of the network to which this route is attached.
destRange string	The route's address destination.
priority integer	Priority for this route. Number should be a positive integer. Priority is used to break ties when there is more than one matching route of maximum length.
nextHopNetwork string	The next hop handles the matching packets for this route. It can be an instance, an IP address or the default internet gateway.
selfLink string	Server-defined URL for the resource.
kind string	Type of the resource.
networkName string	Name of the network to which this route is attached.

Retrieve a route

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routes/6918030089270271318"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "6918030089270271318",
    "creationTimestamp": "2020-05-21T08:52:26.010-07:00",
    "name": "default-route-0f2f9d9f9910829a",
    "description": "Default local route to the subnetwork 10.172.0.0/20.",
    "network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
    "destRange": "10.172.0.0/20",
    "priority": 0,
    "nextHopNetwork": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/routes/default-route-0f2f9d9f9910829a",
    "kind": "compute#route",
    "networkName": "default"
  }
}

GET /services/:service_code/:environment_name/routes/:id

Retrieve a route in a given environment.

Attributes
id string	The route's id.
creationTimestamp string	Creation timestamp in RFC3339 text format.
name string	The route's name.
description string	An optional description of this resource.
network string	URL of the network to which this route is attached.
destRange string	The route's address destination.
priority integer	Priority for this route. Number should be a positive integer. Priority is used to break ties when there is more than one matching route of maximum length.
nextHopNetwork string	The next hop handles the matching packets for this route. It can be an instance, an IP address or the default internet gateway.
selfLink string	Server-defined URL for the resource.
kind string	Type of the resource.
networkName string	Name of the network to which this route is attached.

Routers

Cloud Router allows to programs custom dynamic routes and it scales with your network traffic. Cloud Router isn't a physical device that might cause a bottleneck. It can't be used by itself. But, it is required or recommended in the following cases:

• Required for Cloud NAT
• Required for Cloud Interconnect and High Availability (HA) VPN
• A recommended configuration option for Classic VPN

List Routers

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routers"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "4369223640569972416",
      "name": "c-router-failover",
      "kind": "compute#router",
      "shortRegion": "europe-west4",
      "description": "Router specific to internal failover VPC",
      "shortNetwork": "failover-vpc-network",
      "network": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/global/networks/failover-vpc-network",
      ....
      ....
    },
    {
      "id": "0569972416436922364",
      "name": "c-router-main",
      "kind": "compute#router",
      "shortRegion": "europe-west2",
      "description": "Router specific to the main VPC",
      "shortNetwork": "main-vpc-network",
      "network": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/global/networks/main-vpc-network",
    },
    .....
    .....
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/routers

Retrieve a list of all cloud routers in a given environment.

Attributes
data Array[Object]	List of cloud routers available in the current environment
metadata Array	A list of meta information about the response data. Contains recordCount which is an indication of the number of routers in the response

Retrieve a Router

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routers/0569972416436922364"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "4369223640569972416",
    "name": "c-router-failover",
    "kind": "compute#router",
    "shortRegion": "europe-west4",
    "description": "Router specific to internal failover VPC",
    "shortNetwork": "failover-vpc-network",
    "network": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/global/networks/failover-vpc-network",
    "region": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/europe-west4",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/europe-west4/routers/c-router-failover",
    "bgp": {
      "advertiseMode": "DEFAULT",
      "asn": 65510
    },
    "bgpPeers": [
      {
        "advertiseMode": "DEFAULT",
        "interfaceName": "if-failover-bgp-session",
        "ipAddress": "169.254.11.1",
        "name": "failover-bgp-session",
        "peerAsn": 64999,
        "peerIpAddress": "169.254.11.2"
      }
    ],
    "interfaces": [
      {
        "name": "if-failover-bgp-session",
        "ipRange": "169.254.11.1/30",
        "linkedVpnTunnel": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/europe-west4/vpnTunnels/failover-vpn-tunnel"
      }
    ]
  }
}

GET /services/:service_code/:environment_name/routers/:id

Retrieve a cloud router in a given environment.

Attributes
id UUID	Unique identifier for this resource.
name string	The display name of the VPN gateway.
kind string	The type of GCP compute resource.
description string	A user-friendly description about the router and its purpose.
shortRegion string	The specific region in which the router resides in.
shortNetwork string	The VPC network to which the router is attached to.
network string	The URI of the VPC network to which the touter is attached to.
region string	The URI of the region in which the router resided in.
selfLink string	Server-defined URL for the resource.
bgp Object	BGP information specific to this router.
bgpPeers Object	BGP information that is configured into the routing stack to establish BGP peering. (Includes: Peer ASN, Interface name, IP address)
interfaces Array[Object]	Router interfaces. Each interface contains either one linked resource or IP address and IP address range.

Create a router

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routers"

Request body example:

{
  "name": "cmc-c-router",
  "shortNetwork": "cmc-vpc",
  "shortRegion": "us-central1",
  "bgp": {
    "asn": 65510
  }
}

POST /services/:service_code/:environment_name/routers

Create a new router

Required
name string	The display name of the router.
shortRegion string	A short version of the region name.
shortNetwork string	A shortened version of the network name that the router is attached to.
bgp.asn string	The BGP Autonomous System Number (ASN) that is to be assigned to this router. Must be a valid ASN between 64512–65534.

Optional
region string	Instead of the shortRegion, the long URI version of the region can also be provided.
network string	Instead of the shortNetwork, the long URI version of the network can also be provided.

Add router interface(s)

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routers/5333546534174463697?operation=addvpntunnelinterface"

Request body example:

{
  "interfaces": [
    {
      "name": "if-cmc-srx-bgp-interface",
      "ipRange": "169.254.13.1/30",
      "linkedVpnTunnel": "https://www.googleapis.com/compute/v1/projects/cmc-junniper-lab-ses/regions/us-central1/vpnTunnels/cmc-srx-vpn-tunnel"
    }
  ]
}

POST /services/:service_code/:environment_name/routers/:id?operation=addvpntunnelinterface

Add one or more interfaces associated to existing Vpn Tunnel(s).

Required
interfaces Array	An array of interfaces to be added to the selected router.
interfaces[*].name string	The name of the interface on the router.
interfaces[*].ipRange string	IP address and range of the interface. The IP range must be in the RFC3927 link-local IP address space. The value must be a CIDR-formatted string, for example: 169.254.0.1/30.
interfaces[*].linkedVpnTunnel string	URI of the linked VPN tunnel, which must be in the same region as the router.

Add BGP peer(s)

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routers/5333546534174463697?operation=addbgppeer"

Request body example:

{
  "bgpPeers": [
    {
      "name": "juniper-srx-bgp-5th-p2",
      "interfaceName": "if-juniper-srx-bgp-3rd-exp",
      "ipAddress": "169.254.13.1",
      "peerIpAddress": "169.254.13.2",
      "peerAsn": 64999
    }
  ]
}

POST /services/:service_code/:environment_name/routers/:id?operation=addbgppeer

Add one or more BGP peers associated to existing router interface(s)

Required
bgpPeers Array	An array of BGP peers to be added to the selected router.
bgpPeers[*].name string	The name of the BGP peer association.
bgpPeers[*].interfaceName string	The router interface through which this BGP peering will be realized.
bgpPeers[*].ipAddress string	The router's IP address on the above interface for this BGP peering. Only IPv4 is supported.
bgpPeers[*].peerIpAddress string	The peer IP address that the BGP peering will try to connect to. Only IPv4 is supported.
bgpPeers[*].peerAsn string	Peer BGP Autonomous System Number (ASN). Each BGP interface may use a different value.

Delete a Router

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/routers/5333546534174463697"

DELETE /services/:service_code/:environment_name/routers/:id

Delete an existing cloud router from the environment.

Optional
selfLink string	The partially qualified Google Cloud selfLink of this router. This should include the projectId, region and the router name delimited by the URL path separator. Ex: project-id/regions/<short-region>/routers/<router-name>

VPN gateways

With Classic VPN, your on-premises hosts communicate through one or more IPsec VPN tunnels to Compute Engine Virtual Machine (VM) instances in your project's VPC networks.

List VPN gateways

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpngateways"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "creationTimestamp": "2019-08-27T06:37:19.149-07:00",
      "description": "",
      "region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
      "network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
      "status": "READY",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
      "forwardingRules": [
        "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp500",
        "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp4500",
        "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-esp"
      ],
      "kind": "compute#targetVpnGateway",
      "externalIp": {},
      "tunnelsName": [],
      "reserveStaticIP": false,
      "id": "3112849056897469664",
      "name": "test-vpn-gw",
      "shortRegion": "us-central1"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/vpngateways

Retrieve a list of all VPN gateways in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description.
externalIp Object	The external IP attached to this VPN gateway.
forwardingRules Array	List of the forwarding rules which are defined for this VPN gateway.
id UUID	Unique identifier for this resource.
name string	The display name of the VPN gateway.
network string	URL of the network to which this VPN gateway is attached.
region string	The URL of the region where the VPN gateway is.
status string	The status of the VPN gateway. One of the following: READY, CREATING, FAILED and DELETING.
selfLink string	Server-defined URL for the resource.

Retrieve a VPN gateway

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpngateways/3112849056897469664"

The above command returns a JSON structured like this:

{
  "data": {
    "creationTimestamp": "2019-08-27T06:37:19.149-07:00",
    "description": "",
    "region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
    "network": "https://www.googleapis.com/compute/v1/projects/test-area/global/networks/default",
    "status": "READY",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
    "forwardingRules": [
        "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp500",
        "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-udp4500",
        "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/forwardingRules/test-vpn-gw-rule-esp"
    ],
    "kind": "compute#targetVpnGateway",
    "externalIp": {},
    "tunnelsName": [],
    "reserveStaticIP": false,
    "id": "3112849056897469664",
    "name": "test-vpn-gw",
    "shortRegion": "us-central1"
  }
}

GET /services/:service_code/:environment_name/vpngateways/:id

Retrieve a VPN gateway in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description.
externalIp Object	The external IP attached to this VPN gateway.
forwardingRules Array	List of the forwarding rules which are defined for this VPN gateway.
id UUID	Unique identifier for this resource.
name string	The display name of the VPN gateway.
network string	URL of the network to which this VPN gateway is attached.
region string	The URL of the region where the VPN gateway is.
status string	The status of the VPN gateway. One of the following: READY, CREATING, FAILED and DELETING.
selfLink string	Server-defined URL for the resource.

Create a VPN gateway

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpngateways"

Request body examples:

{
  "name": "test-my-vpn-gw",
  "description": "my VPN gateway",
  "shortRegion": "us-east4",
  "reserveStaticIP": true
}

{
  "name": "test-other-vpn-gw",
  "description": "my other VPN gateway",
  "shortRegion": "us-east4",
  "shortIP": "my-vpn-gw-ip"
}

POST /services/:service_code/:environment_name/vpngateways

Create a new Classic VPN gateway in a given environment.

Required
name string	The display name of the VPN gateway.
shortRegion string	A short version of the region name.

Optional
description string	An optional description.
shortIP string	The name of the external static IP to use for the VPN gateway.
reserveStaticIP string	A flag to indicate if a new external static IP needs to be reserved for the VPN gateway. This option is mutually exclusive with shortIP.

Delete VPN gateway

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpngateways/3112849056897469664"

The above command returns a JSON structured like this:

{
  "externalIpToRelease": ["32.45.23.54"]
}

DELETE /services/:service_code/:environment_name/vpngateways/:id

Delete a Classic VPN gateway in a given environment.

Optional
externalIpToRelease Array	A list with only one element specifying the IP address to release.

VPN tunnels

With Classic VPN, your on-premises hosts communicate through one or more IPsec VPN tunnels to Compute Engine Virtual Machine (VM) instances in your project's VPC networks.

List VPN tunnels

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpntunnels"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "creationTimestamp": "2019-12-12T06:34:44.930-08:00",
      "description": "",
      "region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
      "targetVpnGateway": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
      "vpnGatewayInterface": 0,
      "peerExternalGatewayInterface": 0,
      "peerIp": "69.196.164.138",
      "sharedSecret": "*************",
      "sharedSecretHash": "AG9FPaFV_aT2jaIN4cdrnDunzHL8",
      "status": "ESTABLISHED",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/vpnTunnels/vt-epk",
      "ikeVersion": 2,
      "detailedStatus": "Tunnel is up and running.",
      "localTrafficSelector": [
        "10.128.0.0/20"
      ],
      "remoteTrafficSelector": [
        "10.177.132.0/22"
      ],
      "kind": "compute#vpnTunnel",
      "gcpVpnGateway": {},
      "shortVpnGateway": "test-vpn-gw",
      "shortNetwork": "test-vpc",
      "address": "34.66.131.105",
      "type": "CLASSIC",
      "id": "8211895554244865771",
      "name": "vt-test-epk",
      "shortRegion": "us-central1"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/vpntunnels

Retrieve a list of all VPN tunnels in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description.
id UUID	Unique identifier for this resource.
gcpVpnGateway Object	The VPN Gateway associated with this tunnel.
ikeVersion integer	IKE protocol version to use when establishing the VPN tunnel with the peer VPN gateway. Acceptable IKE versions are 1 or 2. The default version is 2.
localTrafficSelector string	Local traffic selector to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. By default it's the CIDR associated with the region in which the VPN gateway resides.
name string	The display name of the address.
peerIp string	IP address of the peer VPN gateway in another VPC.
region string	The URL of the region where the VPN tunnel is.
remoteTrafficSelector string	Remote traffic selectors to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. The CIDR associated with the peerIp.
sharedSecret string	Shared secret used to set the secure session between the Cloud VPN gateway and the peer VPN gateway.
status string	The status of the VPN tunnel.
selfLink string	Server-defined URL for the resource.
targetVpnGateway string	The URL of the Target VPN gateway with which this VPN tunnel is associated.
shortVpnGateway string	Name of the VPN gateway with which this VPN tunnel is associated.
shortNetwork string	Name of the network with which this VPN tunnel is associated.
shortRegion string	Name of the region with which the VPN gateway attached to the tunnel is located.
type string	The type of this VPN Tunnel. Only CLASSIC is supported.

Retrieve a VPN tunnel

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpntunnels/8211895554244865771"

The above command returns a JSON structured like this:

{
  "data":{
    "creationTimestamp": "2019-12-12T06:34:44.930-08:00",
    "description": "",
    "region": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1",
    "targetVpnGateway": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
    "vpnGatewayInterface": 0,
    "peerExternalGatewayInterface": 0,
    "peerIp": "69.196.164.138",
    "sharedSecret": "*************",
    "sharedSecretHash": "AG9FPaFV_aT2jaIN4cdrnDunzHL8",
    "status": "ESTABLISHED",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/vpnTunnels/vt-epk",
    "ikeVersion": 2,
    "detailedStatus": "Tunnel is up and running.",
    "localTrafficSelector": [
      "10.128.0.0/20"
    ],
    "remoteTrafficSelector": [
      "10.177.132.0/22"
    ],
    "kind": "compute#vpnTunnel",
    "gcpVpnGateway": {},
    "shortVpnGateway": "test-vpn-gw",
    "shortNetwork": "test-vpc",
    "address": "34.66.131.105",
    "type": "CLASSIC",
    "id": "8211895554244865771",
    "name": "vt-test-epk",
    "shortRegion": "us-central1"
  }
}

GET /services/:service_code/:environment_name/vpntunnels/:id

Retrieve a VPN tunnel in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description.
id UUID	Unique identifier for this resource.
gcpVpnGateway Object	The VPN Gateway associated with this tunnel.
ikeVersion integer	IKE protocol version to use when establishing the VPN tunnel with the peer VPN gateway. Acceptable IKE versions are 1 or 2. The default version is 2.
localTrafficSelector string	Local traffic selector to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. By default it's the CIDR associated with the region in which the VPN gateway resides.
name string	The display name of the address.
peerIp string	IP address of the peer VPN gateway in another VPC.
region string	The URL of the region where the VPN tunnel is.
remoteTrafficSelector string	Remote traffic selectors to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string. Only IPv4 is supported. The CIDR associated with the peerIp.
sharedSecret string	Shared secret used to set the secure session between the Cloud VPN gateway and the peer VPN gateway.
status string	The status of the VPN tunnel.
selfLink string	Server-defined URL for the resource.
targetVpnGateway string	The URL of the Target VPN gateway with which this VPN tunnel is associated.
shortVpnGateway string	Name of the VPN gateway with which this VPN tunnel is associated.
shortNetwork string	Name of the network with which this VPN tunnel is associated.
shortRegion string	Name of the region with which the VPN gateway attached to the tunnel is located.
type string	The type of this VPN Tunnel. Only CLASSIC is supported.

Create a VPN tunnel

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpntunnels"

Request body example:

{
  "name": "test-my-vpn-tunnel",
  "description": "my VPN tunnel",
  "targetVpnGateway": "https://www.googleapis.com/compute/v1/projects/test-area/regions/us-central1/targetVpnGateways/test-vpn-gw",
  "peerIP": "69.196.164.138",
  "ikeVersion": 2,
  "sharedSecret": "mysecret",
  "remoteTrafficSelector": "10.128.0.0/20",
  "localTrafficSelector": ""
}

POST /services/:service_code/:environment_name/vpntunnels

Create a new Classic VPN tunnel in a given environment.

Required
name string	The display name of the VPN tunnel.
ikeVersion string	KE protocol version to use when establishing the VPN tunnel with the peer VPN gateway. Acceptable IKE versions are 1 or 2. The default version is 2.
peerIP string	The IP address of the Virtual Private Cloud (VPC) the tunnel will connect to.
remoteTrafficSelector string	Remote traffic selectors to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string.
sharedSecret string	TShared secret used to set the secure session between the Cloud VPN gateway and the peer VPN gateway.
targetVpnGateway string	URL of the Target VPN gateway with which this VPN tunnel is associated.

Optional
description string	An optional description.
localTrafficSelector string	Local traffic selector to use when establishing the VPN tunnel with the peer VPN gateway. The value should be a CIDR formatted string.

Delete VPN Tunnel

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/vpntunnels/8211895554244865771"

The above command returns a JSON structured like this:

{
  "vpnGatewayToDelete": "3932849056897469665",
  "gcpVpnGateway": {
    "externalIpToRelease": ["32.45.23.54"]
  }
}

DELETE /services/:service_code/:environment_name/vpntunnels/:id

Delete a Classic VPN tunnel in a given environment.

Optional
vpnGatewayToDelete string	The ID of the VPN gateway to delete after deleting the VPN tunnel.
gcpVpnGateway.externalIpToRelease Array	A list with only one element specifying the IP address to release.

Subnets

Create and manage your subnets. Subnets belongs to a network.

List subnets

curl -X GET \
  -H "mc-api-key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/subnetworks"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "creationTimestamp": "2020-05-28T07:20:17.315-07:00",
      "fingerprint": "resource_fingerprint",
      "gatewayAddress": "10.128.0.1",
      "ipCidrRange": "10.128.0.0/20",
      "kind": "compute#subnetwork",
      "network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
      "privateIpGoogleAccess": false,
      "region": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
      "shortNetwork": "default",
      "id": "resource_id",
      "name": "default",
      "shortRegion": "us-central1"
    }],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/subnetworks

Retrieve a list of all subnets in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
fingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
gatewayAddress string	Second address in the primary IP range for the subnet.
ipCidrRange string	Primary IP address range for the following resources: VM instances, internal load balancers, and internal protocol forwarding.
kind string	Type of the resource.
network string	Server-defined URL for the VPC network that contains the subnet.
privateIpGoogleAccess string	Whether the Private Google Access is configured.
region Array[Disk]	Server-defined URL for the region name.
selfLink string	Server-defined URL for this resource.
shortNetwork string	Display name of the VPC network that contains the subnet.
id UUID	The id of the subnet.
name string	The display name of the subnet.
shortRegion string	A short version of the region name.

Filters

GET /services/:service_code/:environment_name/subnetworks?network=:VPC-network-selflink

Retrieve a list of all networks in a given environment and [VPC-network].

Retrieve a subnet

curl -X GET \
  -H "mc-api-key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/subnetworks/8841143494674098002"

The above command returns a JSON structured like this:

{
  "data": {
    "creationTimestamp": "2020-06-12T08:05:33.741-07:00",
    "fingerprint": "resource_fingerprint",
    "gatewayAddress": "10.128.0.1",
    "ipCidrRange": "10.128.0.0/20",
    "kind": "compute#subnetwork",
    "network": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/networks/default",
    "privateIpGoogleAccess": false,
    "region": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/us-central1/subnetworks/default",
    "shortNetwork": "default",
    "id": "resource_id",
    "name": "default",
    "shortRegion": "us-central1"
  }
}

GET /services/:service_code/:environment_name/subnetworks/:id

Retrieve information about a subnet.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
fingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
gatewayAddress string	Second address in the primary IP range for the subnet.
ipCidrRange string	Primary IP address range for the following resources: VM instances, internal load balancers, and internal protocol forwarding.
kind string	Type of the resource.
network string	Server-defined URL for the VPC network that contains the subnet.
privateIpGoogleAccess string	Whether the Private Google Access is configured.
region Array[Disk]	Server-defined URL for the region name.
selfLink string	Server-defined URL for this resource.
shortNetwork string	Display name of the VPC network that contains the subnet.
id UUID	The id of the subnet.
name string	The display name of the subnet.
shortRegion string	A short version of the region name.

Create a subnet

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/subnetworks"

Request body example:

{
  "name": "my-subnet",
  "shortRegion": "northamerica-northeast1",
  "ipCidrRange": "10.0.0.0/9",
  "network": "https://www.googleapis.com/compute/v1/projects/my-project/global/networks/my-network"
}

POST /services/:service_code/:environment_name/subnetworks

Create a new subnet

Required
name string	The display name of the subnet.
shortRegion string	A short version of the region name.
network string	The selflink of the network.
ipCidrRange string	The CIDR IP range of the subnet.

Optional
description string	Description of the subnet.

Delete a subnet

curl -X DELETE \
  -H "mc-api-key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/subnetworks/8841143494674098002"

DELETE /services/:service_code/:environment_name/subnetworks/:id

Delete an existing subnet

Load balancing

Load balancer

HTTP(S) load balancing can balance HTTP and HTTPS traffic across multiple backend instances, across multiple regions. Your entire app is available via a single global IP address, resulting in a simplified DNS setup. HTTP(S) load balancing is scalable, fault-tolerant, requires no pre-warming, and enables content-based load balancing. For HTTPS traffic, it provides SSL termination and load balancing.

List load balancers

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/loadbalancers"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "8268558443601303519",
            "forwardingRules": [
                "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-cme",
                "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-qxq"
            ],
            "targetProxies": [
                "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/tp-test-fkb",
                "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpsProxies/tp-test-rqi"
            ],
            "urlMap": "https://www.googleapis.com/compute/v1/projects/test-area/global/urlMaps/um-test-dfr",
            "backendServices": [
                "https://www.googleapis.com/compute/v1/projects/test-area/global/backendServices/be-test-jik"
            ],
            "name": "um-test-dfr"
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/loadbalancers

Retrieve a list of all load balancers in a given environment.

Attributes
backendServices List	The list of backends for this resource.
forwardingRules List	The list of forwarding rules for this resource.
id String	The id of this resource, which should be the same id as corresponding Url Map.
name String	The name of this resource.
targetProxies List	The list of target proxies for this resource.
urlMap String	Server-defined URL for corresponding url map.

Retrieve a load balancer

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/loadbalancers/8268558443601303519"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "8268558443601303519",
        "forwardingRules": [
            "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-cme",
            "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/gfr-test-qxq"
        ],
        "targetProxies": [
            "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/tp-test-fkb",
            "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpsProxies/tp-test-rqi"
        ],
        "urlMap": "https://www.googleapis.com/compute/v1/projects/test-area/global/urlMaps/um-test-dfr",
        "backendServices": [
            "https://www.googleapis.com/compute/v1/projects/test-area/global/backendServices/be-test-jik"
        ],
        "name": "um-test-dfr"
    }
}

GET /services/:service_code/:environment_name/loadbalancers/:id

Retrieve a load balancer in a given environment.

Attributes
backendServices List	The list of backends for this resource.
forwardingRules List	The list of forwarding rules for this resource.
id String	The id of this resource, which should be the same id as corresponding Url Map.
name String	The name of this resource.
targetProxies List	The list of target proxies for this resource.
urlMap String	Server-defined URL for corresponding url map.

Create a load balancer

curl -X POST \
  -H 'MC-Api-Key: your_api_key' \
  -H "Content-Type: application/json" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/loadbalancers"

Request body examples:

// Creating loadbalancer with ephemeral IP
{
    "name":"my-loadbalancer-name",
    "shortBackend": "my-backend-backend",
    "shortProtocol": "HTTP",
    "shortPort": "80"
}

// Creating loadbalancer with existing IP
{
    "name":"my-loadbalancer-name",
    "shortBackend": "my-backend-backend",
    "shortProtocol": "HTTP",
    "shortPort": "80",
    "shortIP": "my-ip-name",
}

// Creating loadbalancer with new static IP
{
    "name":"my-loadbalancer-name",
    "shortBackend": "my-backend-backend",
    "shortProtocol": "HTTP",
    "shortPort": "80",
    "reserveStaticIP": true
}

// Creating loadbalancer with HTTPS protocol
{
    ...
    "shortPort": "443",
    "shortCertificate": "my-SSL-certificate"
}

POST /services/:service_code/:environment_name/loadbalancers

Create a new load balancer.

Required
name string	The display name of the load balancer.
shortBackend string	The existing backend serivce that will be attached to this load balancer.
shortProtocol string	The protocol of this resource.
shortPort string	The port number of this resource.

Optional
reserveStaticIP boolean	If the value is false and if no shortIP is provided, an ephemeral external IP address will be assigned. If the value is true, a new static IP would be reserved and provided to the resource.
shortIP string	The name of an existing global external IP address assigned to the frontend. This argument is only valid in conjunction with reserveStaticIP being false. If the value is false and shortIP is provided, then the existing external IP address will be assigned. If the value is true, a new external static IP will be reserved and assigned.
shortCertificate string	The name of the SSL certificate that will be attached to the target proxy if HTTPS is selected. (Required if HTTPS is selected for shortProtocol)

Delete a load balancer

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/loadbalancers/8268558443601303519"

The above command returns a JSON structured like this:

{
  "shortBackendsToDelete": ["be-test-jik", "be-other-srd"],
  "shortHealthChecksToDelete": ["hc-test-olp", "hc-other-kop"],
  "shortSslCertificatesToDelete": ["sc-test-ert"]
}

DELETE /services/:service_code/:environment_name/loadbalancers/:id

Delete an existing load balancer.

Optional
shortBackendsToDelete List	A list of backend services to delete.
shortHealthChecksToDelete List	A list of health checks to delete.
shortSslCertificatesToDelete List	A list of SSL certificates to delete.

Forwarding rules

A forwarding rule and its corresponding IP address represent the frontend configuration of a load balancer.

List forwarding rules

curl -X GET \
  -H 'MC-Api-key: your_api_key'
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/forwardingrules"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "creationTimestamp": "2019-10-22T15:23:35.006-07:00",
      "description": "",
      "IPAddress": "35.227.251.25",
      "IPProtocol": "TCP",
      "ipVersion": "IPV4",
      "kind": "compute#forwardingRule",
      "loadBalancingScheme": "EXTERNAL",
      "networkTier": "PREMIUM",
      "portRange": "80-80",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/my-forwarding-rule",
      "target": "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/my-target-proxy",
      "shortTarget": "my-target-proxy",
      "id": "4724455712741277576",
      "name": "my-forwarding-rule"
   }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /service/:service_code/:environment_name/forwardingrules

Retrieve a list of all forwarding rules.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
id string	The unique identifier for the resource. This identifier is defined by the server.
IPAddress string	The IP address that this forwarding rule serves.
IPProtocol string	The IP protocol to which this rule applies. The default protocol is TCP.
ipVersion string	The IP version that will be used by this forwarding rule. The default IP version is IPV4.
kind string	Type of the resource.
loadBalancingScheme string	Specifies the forwarding rule type. The default value is EXTERNAL.
name string	Name of the resource. Provided by the client when the resource is created.
networkTier string	This signifies the networking tier used for configuring this load balancer.
portRange string	The destination ports that this forwarding rule forwards packets with.
selfLink string	Server-defined URL for this resource.
shortTarget string	The name of the target resource.
target string	The URL of the target resource to receive the matched traffic.

Retrieve a forwarding rule

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/forwardingrules/4724455712741277576"

The above command returns a JSON structured like this:

{
  "data": {
      "creationTimestamp": "2019-10-22T15:23:35.006-07:00",
      "description": "",
      "IPAddress": "35.227.251.25",
      "IPProtocol": "TCP",
      "ipVersion": "IPV4",
      "kind": "compute#forwardingRule",
      "loadBalancingScheme": "EXTERNAL",
      "networkTier": "PREMIUM",
      "portRange": "80-80",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/forwardingRules/my-forwarding-rule",
      "target": "https://www.googleapis.com/compute/v1/projects/test-area/global/targetHttpProxies/my-target-proxy",
      "shortTarget": "my-target-proxy",
      "id": "4724455712741277576",
      "name": "my-forwarding-rule"
   }
}

GET /services/:service_code/:environment_name/forwardingrules/:id

Retrieve a forwarding rule in a given environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
id string	The unique identifier for the resource. This identifier is defined by the server.
IPAddress string	The IP address that this forwarding rule serves.
IPProtocol string	The IP protocol to which this rule applies. The default protocol is TCP.
ipVersion string	The IP version that will be used by this forwarding rule. The default IP version is IPV4.
kind string	Type of the resource.
loadBalancingScheme string	Specifies the forwarding rule type. The default value is EXTERNAL.
name string	Name of the resource. Provided by the client when the resource is created.
networkTier string	This signifies the networking tier used for configuring this load balancer.
portRange string	The destination ports that this forwarding rule forwards packets with.
selfLink string	Server-defined URL for this resource.
shortTarget string	The name of the target resource.
target string	The URL of the target resource to receive the matched traffic.

Create a forwarding rule

curl -X POST \
  -H 'MC-Api-Key: your_api_key' \
  -H "Content-Type: application/json" \
  -d "request _body" \
  "https://cloudmc_endpoint/api/v1/services/gcp/test-area/forwardingrules"

Request body examples:

// Creating a forwarding rule with ephemeral IP
{
  "portRange": "80",
  "name": "my-forwarding-name",
  "shortTarget": "my-target-proxy"
}

// Creating a forwarding rule with new static IP
{
  "portRange": "80",
  "name": "my-forwarding-name", 
  "shortTarget": "my-target-proxy",
  "reserveStaticIP": true
}

// Creating a forwarding rule with ephemeral IP
{
  "portRange": "80",  
  "name": "my-forwarding-name",
  "shortTarget": "my-target-proxy",  
  "shortIPAddress": "my-IP-address"
}

POST /services/:service_code/:environment_name/forwardingrules

Create a new forwarding rule.

Required
name string	The display name of the forwarding rule.
portRange string	The port which will be allocated to the forwarding rule. Supported ports are: 80 or 8080 (HTTP) and 443 (HTTPS).
shortTarget string	The name of the target resource.

Optional
description string	Description of the forwarding rule.
reserveStaticIP boolean	If the value is false and if no shortIPAddress is provided, an ephemeral external IP address will be assigned.
shortIPAddress string	The name of an existing global external IP address assigned to the rule. This argument is only valid in conjunction with reserveStaticIP being false. If the value is false and shortIPAddress is provided, then the existing external IP address will be assigned. If the value is true, a new external static IP will be reserved and assigned.

Delete a forwarding rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/forwardingrules/5459493658413662148"

DELETE /services/:service_code/:environment_name/forwardingrules/:id

Destroy an existing global forwarding rule.

Target proxies

Target proxies route incoming request to either a URL map (HTTP(S) load balancing) or a backend service (SSL/TCP load balancing).

List target proxies

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/targetproxies"

The above command returns a JSON structured like this:

{
  "data": [
    {
       "creationTimestamp": "2019-10-01T08:52:41.664-07:00",
       "id": "2137054791002409126",
       "kind": "compute#targetHttpProxy",
       "name": "targetProxyName",
       "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/targetHttpProxies/targetProxyName",
       "urlMap": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/urlMaps/urlMapName",
       "type": "HTTP",
       "shortUrlMap": "urlMapName"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/targetproxies

Retrieve a list of all target proxies in an environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
id UUID	The id of the backend service.
kind string	Type of the resource. Either compute#targetHttpProxy or compute#targetHttpsProxy for target proxies.
name string	Name of the resource.
selfLink string	Server-defined URL for the resource.
shortUrlMap string	A short version of the URL map name.
shortCertificates string	A short version of the SSL certificate name.
type enum	A short version of the kind of resource. Either HTTP or HTTPS.
urlMap string	URL to the UrlMap resource that defines the mapping from URL to the BackendService.

Retrieve a target proxy

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/targetproxies/2137054791002409126"

The above command returns a JSON structured like this:

{
    "data": {
         "creationTimestamp": "2019-10-01T08:52:41.664-07:00",
         "id": "2137054791002409126",
         "kind": "compute#targetHttpsProxy",
         "name": "targetProxyName",
         "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/targetHttpsProxies/targetProxyName",
         "sslCertificates": [
           "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/sslCertificates/sslCertificateName"
         ],
         "type": "HTTPS",
         "urlMap": "https://www.googleapis.com/compute/v1/projects/test-area-oox/global/urlMaps/urlMapName",
         "shortUrlMap": "urlMapName",
         "shortCertificates": "sslCertificateName"
    }
}

GET /services/:service_code/:environment_name/targetproxies/:id

Retrieve a target proxy in an environment.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
id UUID	The id of the backend service.
kind string	Type of the resource. Either compute#targetHttpProxy or compute#targetHttpsProxy for target proxies.
name string	Name of the resource.
selfLink string	Server-defined URL for the resource.
shortUrlMap string	A short version of the URL map name.
shortCertificates string	A short version of the SSL certificate name.
type enum	A short version of the kind of resource. Either HTTP or HTTPS.
urlMap string	URL to the UrlMap resource that defines the mapping from URL to the BackendService.

Create a target proxy

# Example request: Specifying an existing URL map
curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/targetProxies"

Request body examples:

// Specifying an existing URL map
{
   "name": "targetProxyName",
   "type": "HTTPS",
   "shortUrlMap": "urlMapName",
   "shortCertificates": "sslCertificateName"
}

// Specifying a backend service, a default URL map will be created automatically
{
   "name": "targetProxyName",
   "type": "HTTPS",
   "shortBackend": "backendServicesName",
   "shortCertificates": "sslCertificateName"
}

POST /services/:service_code/:environment_name/targetProxies

Create a new target proxy.

Required
name string	Name of the resource.
type enum	A short version of the kind of resource.
shortBackend string	A short version of the backend service name. The shortBackend and shortUrlMap attributes are mutually exclusive.
shortCertificates string	A short version of the SSL certificate name. Specifying an SSL certificate is only required when creating an HTTPS target proxy.
shortUrlMap string	A short version of the URL map name. The shortBackend and shortUrlMap attributes are mutually exclusive.

Delete a target proxy

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/targetproxies/2137054791002409126"

DELETE /services/:service_code/:environment_name/targetproxies/:id

Delete an existing target proxy. A target proxy can only be deleted if it is not used in any urlMap.

Backend services

A backend service directs traffic to backends, such as instance groups.

List backend services

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/backendservices"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "affinityCookieTtlSec": 0,
      "backends": [
        {
          "balancingMode": "UTILIZATION",
          "capacityScaler": 1.0,
          "description": "",
          "group": "https://www.googleapis.com/compute/v1/projects/testAreaName/zones/us-central1-a/instanceGroups/instanceGroupName",
          "maxUtilization": 0.8
        }
      ],
      "connectionDraining": {
        "drainingTimeoutSec": 300
      },
      "creationTimestamp": "2019-09-23T12:57:58.039-07:00",
      "description": "",
      "enableCDN": false,
      "fingerprint": "nH5X-L6Fovs=",
      "healthChecks": [
        "https://www.googleapis.com/compute/v1/projects/testAreaName/global/healthChecks/healthCheckName"
      ],
      "kind": "compute#backendService",
      "loadBalancingScheme": "EXTERNAL",
      "port": 80,
      "portName": "http",
      "protocol": "HTTP",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/testAreaName/global/backendServices/backendServiceName",
      "sessionAffinity": "NONE",
      "timeoutSec": 30,
      "shortHealthChecks": "healthCheckName",
      "shortBackends": "instanceGroupName",
      "id": "526709884866305321",
      "name": "backendServiceName"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/backendservices

Retrieve a list of all backend services in an environment.

Attributes
affinityCookieTtlSec number	If set to 0, the cookie is non-persistent and lasts only until the end of the browser session (or equivalent). The maximum allowed value is one day (86,400).
backends object	The list of backends that serve this BackendService.
connectionDraining object	-
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of the resource.
enableCDN boolean	If true, enables Cloud CDN for the backend service. Only applicable if the loadBalancingScheme is EXTERNAL and the protocol is HTTP or HTTPS.
fingerprint string	Fingerprint of this resource. A hash of the contents stored in this object.
healthChecks string	The list of URLs to the HttpHealthCheck or HttpsHealthCheck resource for health checking this BackendService. Currently at most one health check can be specified.
id UUID	The id of the backend service.
kind string	Type of the resource. Always compute#backendService for backend services.
loadBalancingScheme enum	Indicates whether the backend service will be used with internal or external load balancing. Possible values are INTERNAL and EXTERNAL.
name string	Name of the resource.
portName string	A named port on a backend instance group representing the port for communication to the backend VMs in that group.
protocol enum	The protocol this BackendService uses to communicate with backends. Possible values are HTTP or HTTPS.
selfLink string	Server-defined URL for the resource.
sessionAffinity enum	Type of session affinity to use. The default is NONE.
shortBackends string	A short version of the list of backends.
shortHealthChecks string	A short version of the health checks.
timeoutSec number	The default is 30 seconds.

Retrieve a backend service

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/backendservices"

The above command returns a JSON structured like this:

{
    "data": {
      "affinityCookieTtlSec": 0,
      "backends": [
        {
          "balancingMode": "UTILIZATION",
          "capacityScaler": 1.0,
          "description": "",
          "group": "https://www.googleapis.com/compute/v1/projects/testAreaName/zones/us-central1-a/instanceGroups/instanceGroupName",
          "maxUtilization": 0.8
        }
      ],
      "connectionDraining": {
        "drainingTimeoutSec": 300
      },
      "creationTimestamp": "2019-09-23T12:57:58.039-07:00",
      "description": "",
      "enableCDN": false,
      "fingerprint": "nH5X-L6Fovs=",
      "healthChecks": [
        "https://www.googleapis.com/compute/v1/projects/testAreaName/global/healthChecks/healthCheckName"
      ],
      "kind": "compute#backendService",
      "loadBalancingScheme": "EXTERNAL",
      "port": 80,
      "portName": "http",
      "protocol": "HTTP",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/testAreaName/global/backendServices/backendServiceName",
      "sessionAffinity": "NONE",
      "timeoutSec": 30,
      "shortHealthChecks": "healthCheckName",
      "shortBackends": "instanceGroupName",
      "id": "526709884866305321",
      "name": "backendServiceName"
    }  
}

GET /services/:service_code/:environment_name/backendservices/:id

Retrieve a backend service in an environment.

Attributes
affinityCookieTtlSec number	If set to 0, the cookie is non-persistent and lasts only until the end of the browser session (or equivalent). The maximum allowed value is one day (86,400).
backends object	The list of backends that serve this BackendService.
connectionDraining object	-
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of the resource.
enableCDN boolean	If true, enables Cloud CDN for the backend service. Only applicable if the loadBalancingScheme is EXTERNAL and the protocol is HTTP or HTTPS.
fingerprint string	Fingerprint of this resource. A hash of the contents stored in this object.
healthChecks string	The list of URLs to the HttpHealthCheck or HttpsHealthCheck resource for health checking this BackendService. Currently at most one health check can be specified.
id UUID	The id of the backend service.
kind string	Type of the resource. Always compute#backendService for backend services.
loadBalancingScheme enum	Indicates whether the backend service will be used with internal or external load balancing. Possible values are INTERNAL and EXTERNAL.
name string	Name of the resource.
portName string	A named port on a backend instance group representing the port for communication to the backend VMs in that group.
protocol enum	The protocol this BackendService uses to communicate with backends. Possible values are HTTP or HTTPS.
selfLink string	Server-defined URL for the resource.
sessionAffinity enum	Type of session affinity to use. The default is NONE.
shortBackends string	A short version of the list of backends.
shortHealthChecks string	A short version of the health checks.
timeoutSec number	The default is 30 seconds.

Create backend service

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/backendservices"

Request body example:

{
  "name": "my-instance",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-a",
  "bootDiskType": "pd-standard",
  "bootDiskSizeInGb": "10",
  "cpuCount": "2",
  "memoryInGB": "4.5",
  "osImageSelfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
  "externalIp": {
    "id": "3645738160550100933"
  }
}

POST /services/:service_code/:environment_name/backendservices

Create a new backend service.

Required
name string	The display name of the backend service.
shortBackends string	A short version of the list of backends.
shortHealthChecks string	A short version of the health checks.

Delete a backend service

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/backendservices/2570199154720991429"

DELETE /services/:service_code/:environment_name/backendservices/:id

Delete an existing backend service. A backend service can only be deleted if it is not used in any urlMap.

SSL Certificates

Represents an SSL Certificate resource.

List ssl certificate

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sslcertificates"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "certificate": "-----BEGIN CERTIFICATE-----
      (encoded certificate body in here)
      -----END CERTIFICATE-----",
      "creationTimestamp": "2019-10-02T10:36:39.138-07:00",
      "id": "6911678730387654321",
      "kind": "compute#sslCertificate",
      "name": "ssl-root-ozv",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/sslCertificates/ssl-root-ozv",
      "domain": "ApiDocsDomain",
      "organization": "ApiDocsOrg",
      "validUntil": "2020-09-30",
      "validFrom": "2019-10-01",
      "issuerName": "ApiDocs",
      "uploadDate": "2019-10-02"
    },
    {
      "certificate": "-----BEGIN CERTIFICATE-----
      (encoded certificate body in here)
      -----END CERTIFICATE-----",
      "creationTimestamp": "2019-10-01T13:33:36.409-07:00",
      "id": "2973924929495238351",
      "kind": "compute#sslCertificate",
      "name": "ssl-root-tcs",
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/sslCertificates/ssl-root-tcs",
      "domain": "ApiDocsDomain",
      "organization": "ApiDocsOrg",
      "validUntil": "2020-09-30",
      "validFrom": "2019-10-01",
      "issuerName": "ApiDocs",
      "uploadDate": "2019-10-01"
    },
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/sslcertificates

Retrieve a list of all ssl certificates in an environment.

Attributes
certificate String	A local certificate file. The certificate must be in PEM format. The certificate chain must be no greater than 5 certs long. The chain must include at least one intermediate cert.
creationTimestamp String	Creation timestamp in RFC3339 text format.
domain string	The domain name on certificate.
id String	The id of the ssl certificate.
issuerName string	Name of the issuer.
kind string	Type of the resource. Always compute#sslCertificate for ssl certificate.
name string	Name of the resource.
organization string	The organization to which certificate belongs.
selfLink string	Server-defined URL for the resource.
uploadDate string	Date when certificate is uploaded.
validFrom string	Date from when certificate is valid.
validUntil string	Date up until which certificate is valid.

Retrieve a ssl certificate

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sslcertificates/6911678730334723784"

The above command returns a JSON structured like this:

{
  "data": {
    "certificate": "-----BEGIN CERTIFICATE-----
    (encoded certificate body in here)
    -----END CERTIFICATE-----",
    "creationTimestamp": "2019-10-02T10:36:39.138-07:00",
    "id": "6911678730334723784",
    "kind": "compute#sslCertificate",
    "name": "ssl-root-ozv",
    "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area/global/sslCertificates/ssl-root-ozv",
    "domain": "ApiDocsDomain",
    "organization": "ApiDocsOrg",
    "validUntil": "2020-09-30",
    "validFrom": "2019-10-01",
    "issuerName": "ApiDocs",
    "uploadDate": "2019-10-02"
  }
}

GET /services/:service_code/:environment_name/sslcertificates/:id

Retrieve a ssl certificate in an environment.

Attributes
certificate String	A local certificate file. The certificate must be in PEM format. The certificate chain must be no greater than 5 certs long. The chain must include at least one intermediate cert.
creationTimestamp String	Creation timestamp in RFC3339 text format.
domain string	The domain name on certificate.
id String	The id of the ssl certificate.
issuerName string	Name of the issuer.
kind string	Type of the resource. Always compute#sslCertificate for ssl certificate.
name string	Name of the resource.
organization string	The organization to which certificate belongs.
selfLink string	Server-defined URL for the resource.
uploadDate string	Date when certificate is uploaded.
validFrom string	Date from when certificate is valid.
validUntil string	Date up until which certificate is valid.

Create ssl certificate

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sslcertificates"

Request body example:

{
    "name": "ssl-root-rny",
    "privateKey": "-----BEGIN RSA PRIVATE KEY-----
  (encoded private key body in here)
  -----END RSA PRIVATE KEY-----",
    "certificate": "-----BEGIN CERTIFICATE-----
  (encoded certificate body in here)
  -----END CERTIFICATE-----",
    "chainCertificate": "-----BEGIN CERTIFICATE-----
  (encoded chain certificate body in here)
  -----END CERTIFICATE-----",
    "description": "Api docs demo certificate"
}

POST /services/:service_code/:environment_name/sslcertificates

Create a new ssl certificate.

Required
certificate string	Public key certificate in PEM format.
chainCertificate string	Chain certificates in PEM format, if there are any. Also total number of certificates, including main certificate cannot be more than 5.
description string	A short description of this certificate.
name string	The display name of the ssl certificate.
privateKey string	The privateKey associated to certificate in PEM format.

Delete a ssl certificate

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/sslcertificates/2973924929495212345"

DELETE /services/:service_code/:environment_name/sslcertificates/:id

Delete an existing SSL certificate. SSL certificate can only be deleted if it is not used in any target proxy.

Kubernetes

Clusters

List your Kubernetes clusters.

List clusters

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/clusters"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "status": "RUNNING",
      "nodeCount": 3,
      "endpoint": "104.197.118.234",
      "location": "us-central1-a",
      "creationTimestamp": "2019-07-08T18:45:16+00:00",
      "caCert": "LS0tLS1CRUdJTiBD...",
      "addressRange": "10.4.0.0/14",
      "networkName": "default",
      "subnetName": "default",
      "currentMasterVersion": "1.15.12-gke.20",
      "cpuCount": 12,
      "memoryInGB": 24.00,
      "labels": {
        "key1": "value1"
      },
      "nodePoolMachineTypes": {
            "e2-medium": 1,
      },
      "id": "projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1",
      "name": "standard-cluster-1"
    },
    {
      "status": "RUNNING",
      "nodeCount": 1,
      "endpoint": "34.66.215.161",
      "location": "us-central1-a",
      "creationTimestamp": "2019-07-08T14:59:19+00:00",
      "caCert": "LS0tLS1CRUdJS0K...",
      "addressRange": "10.44.0.0/14",
      "networkName": "default",
      "subnetName": "default",
      "currentMasterVersion": "1.15.12-gke.20",
      "cpuCount": 6,
      "memoryInGB": 12.00,
      "labels": {},
      "nodePoolMachineTypes": {
        "e2-custom-2-1024": 3
        },
      "id": "projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/your-first-cluster-1",
      "name": "your-first-cluster-1",
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/clusters

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
nodeCount number	Number of nodes in the cluster.
endpoint string	The IP address of the cluster's master node. All interactions with the Kubernetes API are done through the master node.
location string	The zone or region in which the cluster is running. For regional clusters, your cluster nodes may span multiple zones within the region.
status string	The status of the cluster.
caCert string	The base64 encoded certificate authority certificate for the cluster.
addressRange string	The IP address range of the container pods in this cluster, in CIDR notation (e.g. 10.96.0.0/14).
networkName string	The name of the Google Compute Engine network to which the cluster is connected.
subnetName string	The name of the Google Compute Engine subnetwork to which the cluster is connected.
currentMasterVersion string	The current software version of the master endpoint.
cpuCount int	The sum of CPU cores of all compute instances of the cluster.
memoryInGB double	The sum of memory allocated for all compute instances of the cluster.
labels Map	The resource labels for the cluster to use to annotate any related Google Compute Engine resources.
nodePoolMachineTypes Map	The machine type of the nodepools of the cluster, and the number of machines with that type for the cluster.
id string	The cluster is uniquely identified by the project name, location and cluster name.
name string	The name of the cluster.

Retrieve a cluster

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/clusters/standard-cluster-1/projects/testarea-ugx/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": {
      "status": "RUNNING",
      "nodeCount": 3,
      "endpoint": "104.197.118.234",
      "location": "us-central1-a",
      "creationTimestamp": "2019-07-08T18:45:16+00:00",
      "caCert": "LS0tLS1CRUdJTiBD...",
      "addressRange": "10.4.0.0/14",
      "networkName": "default",
      "subnetName": "default",
      "currentMasterVersion": "1.15.12-gke.20",
      "cpuCount": 12,
      "memoryInGB": 24.00,
      "labels": {
        "key1": "value1"
      },
      "nodePoolMachineTypes": {
      "e2-medium": 1,
    },

      "id": "projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1",
      "name": "standard-cluster-1"
    }
}

GET /services/:service_code/:environment_name/clusters/:cluster_id

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
nodeCount number	Number of nodes in the cluster.
endpoint string	The IP address of the cluster's master node. All interactions with the Kubernetes API are done through the master node.
location string	The zone or region in which the cluster is running. For regional clusters, your cluster nodes may span multiple zones within the region.
status string	The status of the cluster.
caCert string	The base64 encoded certificate authority certificate for the cluster.
addressRange string	The IP address range of the container pods in this cluster, in CIDR notation (e.g. 10.96.0.0/14).
networkName string	The name of the Google Compute Engine network to which the cluster is connected.
subnetName string	The name of the Google Compute Engine subnetwork to which the cluster is connected.
currentMasterVersion string	The current software version of the master endpoint.
cpuCount int	The sum of CPU cores of all compute instances of the cluster.
memoryInGB double	The sum of memory allocated for all compute instances of the cluster.
labels Map	The resource labels for the cluster to use to annotate any related Google Compute Engine resources.
nodePoolMachineTypes Map	The machine type of the nodepools of the cluster, and the number of machines with that type for the cluster.
id string	The cluster is uniquely identified by the project name, location and cluster name.
name string	The name of the cluster.
caCert string	The base64 encoded certificate authority certificate for the cluster.

Create a cluster

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/clusters"

Request body examples:

// Create a cluster
{
  "name": "my-cluster",
  "shortRegion": "northamerica-northeast1",
  "shortZone": "northamerica-northeast1-a",
  "currentMasterVersion": "1.17.12-gke.1501",
  "nodeCount":"3",
  "nodeType":"e2-highcpu-16",
  "networkName": "default",
  "subnetName": "default"
}

POST /services/:service_code/:environment_name/clusters

Create a new cluster.

Required
name string	The display name of the cluster.
shortRegion string	A short version of the region name.
shortZone string	A short version of the zone name.
currentMasterVersion string	The version of GKE used for this cluster.
nodeCount string	The number of nodes in the primary node pool of this cluster. This must be greater than 0.
nodeType string	The machine types of the nodes in the default node pool of this cluster.
networkName string	The network that the Kubernetes cluster is in.
subnetName string	Subnetwork to which the cluster will belong. The subnetwork specified must belong the network specified.

Delete a cluster

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/gcp/test-area/clusters/projects/cmc-test-area-ugx/locations/us-central1-c/clusters/cluster-1"

DELETE /services/:service_code/:environment_name/clusters/:id

Delete a cluster. A cluster can only be deleted if it is in RUNNING or ERROR state.

The above command returns a JSON structured like this:

{
  "taskId": "3e4d4466-ce4b-404b-ada5-ee5a3fb76f4e",
  "taskStatus": "PENDING"
}

Namespaces

List namespaces

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "default",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 4
  }
}

GET /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id

Retrieve a list of all namespaces in a given environment.

Required
cluster_id string	The id of the cluster in which to list the namespaces.

Attributes
id string	The id of the namespace.
apiVersion string	APIVersion defines the versioned schema of this representation of a namespace object
metadata object	The metadata of the namespace
spec object	The specification describes the attributes on a namespace.
status object	The status information of the namespace

Get a namespace

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces/cert-manager?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "default",
    "apiVersion": "v1",
    "kind": "Namespace",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id

Retrieve a namespace and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the namespace.

Attributes
id string	The id of the namespace.
apiVersion string	APIVersion defines the versioned schema of this representation of a namespace object
metadata object	The metadata of the namespace
spec object	The specification describes the attributes on a namespace.
status object	The status information of the namespace

Create a namespace

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces?cluster_id=test-cluster"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Namespace",
  "metadata": {
    "name": "test-namespace"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id

Create a namespace in a given environment.

Required
cluster_id string	The id of the cluster in which to get the namespace.

Required Attributes
apiVersion string	The api version (versioned schema) of the namespace.
metadata object	The metadata of the namespace.
metadata.name string	The name of the namespace.

Return value:

Attributes
taskId string	The id corresponding to the create namespace task.
taskStatus string	The status of the operation.

Delete a namespace

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces/test-namespace?cluster_id=test-cluster"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id

Delete a namespace from a given environment.

Required
cluster_id string	The id of the cluster in which to get the namespace.

Attributes
taskId string	The id corresponding to the delete namespaces task.
taskStatus string	The status of the operation.

Workloads

Pods

List pods

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-aerospike-0/default",
      "metadata": {
        "annotations": {
          "checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
        },
        "creationTimestamp": "2020-01-20T09:35:02.000-05:00",
        "generateName": "my-aerospike-",
        "labels": {
          "app": "aerospike",
          "controller-revision-hash": "my-aerospike-d9969496d",
          "release": "my-aerospike",
          "statefulset.kubernetes.io/pod-name": "my-aerospike-0"
        },
        "name": "my-aerospike-0",
        "namespace": "default",
        "ownerReferences": [
          {
            "apiVersion": "apps/v1",
            "blockOwnerDeletion": true,
            "controller": true,
            "kind": "StatefulSet",
            "name": "my-aerospike",
            "uid": "0b00ea3d-3b92-11ea-935e-025000000001"
          }
        ],
        "resourceVersion": "95058",
        "selfLink": "/api/v1/namespaces/default/pods/my-aerospike-0",
        "uid": "0b055519-3b92-11ea-935e-025000000001"
      },
      "spec": {
        "containers": [
          {
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imagePullPolicy": "IfNotPresent",
            "name": "my-aerospike",
            "ports": [
              {
                "containerPort": 3000,
                "name": "clients",
                "protocol": "TCP"
              },
              {
                "containerPort": 3002,
                "name": "mesh",
                "protocol": "TCP"
              },
              {
                "containerPort": 3003,
                "name": "info",
                "protocol": "TCP"
              }
            ],
            "readinessProbe": {
              "failureThreshold": 3,
              "initialDelaySeconds": 15,
              "periodSeconds": 10,
              "successThreshold": 1,
              "tcpSocket": {
                "port": 3000
              },
              "timeoutSeconds": 1
            },
            "resources": {},
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "volumeMounts": [
              {
                "mountPath": "/etc/aerospike",
                "name": "config-volume"
              },
              {
                "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
                "name": "default-token-64jnc",
                "readOnly": true
              }
            ]
          }
        ],
        "dnsPolicy": "ClusterFirst",
        "enableServiceLinks": true,
        "hostname": "my-aerospike-0",
        "nodeName": "docker-desktop",
        "priority": 0,
        "restartPolicy": "Always",
        "schedulerName": "default-scheduler",
        "securityContext": {},
        "serviceAccount": "default",
        "serviceAccountName": "default",
        "subdomain": "my-aerospike",
        "terminationGracePeriodSeconds": 30,
        "tolerations": [
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/not-ready",
            "operator": "Exists",
            "tolerationSeconds": 300
          },
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/unreachable",
            "operator": "Exists",
            "tolerationSeconds": 300
          }
        ],
        "volumes": [
          {
            "configMap": {
              "defaultMode": 420,
              "items": [
                {
                  "key": "aerospike.conf",
                  "path": "aerospike.conf"
                }
              ],
              "name": "my-aerospike"
            },
            "name": "config-volume"
          },
          {
            "name": "default-token-64jnc",
            "secret": {
              "defaultMode": 420,
              "secretName": "default-token-64jnc"
            }
          }
        ]
      },
      "status": {
        "conditions": [
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "Initialized"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "Ready"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "ContainersReady"
          },
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "PodScheduled"
          }
        ],
        "containerStatuses": [
          {
            "containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
            "lastState": {
              "terminated": {
                "containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
                "exitCode": 255,
                "finishedAt": "2020-01-21T15:04:35.000-05:00",
                "reason": "Error",
                "startedAt": "2020-01-20T10:28:19.000-05:00"
              }
            },
            "name": "my-aerospike",
            "ready": true,
            "restartCount": 2,
            "state": {
              "running": {
                "startedAt": "2020-01-21T15:05:16.000-05:00"
              }
            }
          }
        ],
        "hostIP": "192.168.65.3",
        "phase": "Running",
        "podIP": "10.1.0.129",
        "qosClass": "BestEffort",
        "startTime": "2020-01-20T09:35:02.000-05:00"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/pods?cluster_id=:cluster_id

Retrieve a list of all pods in a given environment.

Required
cluster_id string	The id of the cluster in which to list the pods.

Attributes
id string	The id of the pod.
metadata object	The metadata of the pod.
metadata.annotations map	The annotations of the pod.
metadata.creationTimestamp string	The date of creation of the pod as a string.
metadata.labels map	The labels associated to the pod.
metadata.name string	The name of the pod.
metadata.namespace string	The namespace in which the pod is created.
metadata.uid object	The UUID of the pod.
spec object	The specification used to create and run the pod.
spec.container string	The name of the container running.
status object	The status information of the pod.
status.phase string	The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a pod

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-aerospike-0/default",
      "metadata": {
        "annotations": {
          "checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
        },
        "creationTimestamp": "2020-01-20T09:35:02.000-05:00",
        "generateName": "my-aerospike-",
        "labels": {
          "app": "aerospike",
          "controller-revision-hash": "my-aerospike-d9969496d",
          "release": "my-aerospike",
          "statefulset.kubernetes.io/pod-name": "my-aerospike-0"
        },
        "name": "my-aerospike-0",
        "namespace": "default",
        "ownerReferences": [
          {
            "apiVersion": "apps/v1",
            "blockOwnerDeletion": true,
            "controller": true,
            "kind": "StatefulSet",
            "name": "my-aerospike",
            "uid": "0b00ea3d-3b92-11ea-935e-025000000001"
          }
        ],
        "resourceVersion": "95058",
        "selfLink": "/api/v1/namespaces/default/pods/my-aerospike-0",
        "uid": "0b055519-3b92-11ea-935e-025000000001"
      },
      "spec": {
        "containers": [
          {
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imagePullPolicy": "IfNotPresent",
            "name": "my-aerospike",
            "ports": [
              {
                "containerPort": 3000,
                "name": "clients",
                "protocol": "TCP"
              },
              {
                "containerPort": 3002,
                "name": "mesh",
                "protocol": "TCP"
              },
              {
                "containerPort": 3003,
                "name": "info",
                "protocol": "TCP"
              }
            ],
            "readinessProbe": {
              "failureThreshold": 3,
              "initialDelaySeconds": 15,
              "periodSeconds": 10,
              "successThreshold": 1,
              "tcpSocket": {
                "port": 3000
              },
              "timeoutSeconds": 1
            },
            "resources": {},
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "volumeMounts": [
              {
                "mountPath": "/etc/aerospike",
                "name": "config-volume"
              },
              {
                "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
                "name": "default-token-64jnc",
                "readOnly": true
              }
            ]
          }
        ],
        "dnsPolicy": "ClusterFirst",
        "enableServiceLinks": true,
        "hostname": "my-aerospike-0",
        "nodeName": "docker-desktop",
        "priority": 0,
        "restartPolicy": "Always",
        "schedulerName": "default-scheduler",
        "securityContext": {},
        "serviceAccount": "default",
        "serviceAccountName": "default",
        "subdomain": "my-aerospike",
        "terminationGracePeriodSeconds": 30,
        "tolerations": [
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/not-ready",
            "operator": "Exists",
            "tolerationSeconds": 300
          },
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/unreachable",
            "operator": "Exists",
            "tolerationSeconds": 300
          }
        ],
        "volumes": [
          {
            "configMap": {
              "defaultMode": 420,
              "items": [
                {
                  "key": "aerospike.conf",
                  "path": "aerospike.conf"
                }
              ],
              "name": "my-aerospike"
            },
            "name": "config-volume"
          },
          {
            "name": "default-token-64jnc",
            "secret": {
              "defaultMode": 420,
              "secretName": "default-token-64jnc"
            }
          }
        ]
      },
      "status": {
        "conditions": [
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "Initialized"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "Ready"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "ContainersReady"
          },
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "PodScheduled"
          }
        ],
        "containerStatuses": [
          {
            "containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
            "lastState": {
              "terminated": {
                "containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
                "exitCode": 255,
                "finishedAt": "2020-01-21T15:04:35.000-05:00",
                "reason": "Error",
                "startedAt": "2020-01-20T10:28:19.000-05:00"
              }
            },
            "name": "my-aerospike",
            "ready": true,
            "restartCount": 2,
            "state": {
              "running": {
                "startedAt": "2020-01-21T15:05:16.000-05:00"
              }
            }
          }
        ],
        "hostIP": "192.168.65.3",
        "phase": "Running",
        "podIP": "10.1.0.129",
        "qosClass": "BestEffort",
        "startTime": "2020-01-20T09:35:02.000-05:00"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id

Retrieve a pod and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the pod.

Attributes
id string	The id of the pod.
metadata object	The metadata of the pod.
metadata.annotations map	The annotations of the pod.
metadata.creationTimestamp string	The date of creation of the pod as a string.
metadata.labels map	The labels associated to the pod.
metadata.name string	The name of the pod.
metadata.namespace string	The namespace in which the pod is created.
metadata.uid object	The UUID of the pod.
spec object	The specification used to create and run the pod.
spec.container string	The name of the container running.
status object	The status information of the pod.
status.phase string	The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a pod

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods"
  Content-Type: application/json
  {
      "apiVersion": "v1",
    "kind": "Pod",
      "metadata": {
        "name": "edgar-allen-pod",
          "namespace": "default"
    },
      "spec": {
        "containers": [
            {
                "image": "nginx",
                "name": "nginx"
            }
          ]
      }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/pods

Create a pod in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the pod
metadata object	The metadata of the pod
metadata.name string	The name of the pod
spec object	The specification used to create and run the pod
spec.container.image string	The docker image name
spec.container.name string	The (unique) name of the container specified as a DNS_LABEL

Optional Attributes
metadata.namespace string	The namespace in which the pod is created

Return value:

Attributes
taskId string	The id corresponding to the create pod task.
taskStatus string	The status of the operation.

Replace a pod

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/edgar-allen-pod/default"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "kind": "Pod",
      "metadata": {
        "name": "edgar-allen-pod",
          "namespace": "default"
  },
      "spec": {
        "containers": [
            {
                "image": "nginx",
                "name": "nginx"
            }
          ]
      }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/pods/:id

Replace a pod in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the pod.
metadata object	The metadata of the pod.
metadata.name string	The name of the pod.
spec object	The specification used to replace and run the pod.
spec.container.image string	The docker image name.
spec.container.name string	The (unique) name of the container specified as a DNS_LABEL.

Optional Attributes
metadata.namespace string	The namespace in which the pod is replaced.

Return value:

Attributes
taskId string	The id corresponding to the replace pod task.
taskStatus string	The status of the operation.

Delete a pod

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id

Delete a pod from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the pod.

Attributes
taskId string	The task id related to the delete pod task.
taskStatus string	The status of the operation.

Deployments

List deployments

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "coredns/kube-system",
      "deploymentStatus": "Progressing",
      "readyRatio": "2/2",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 6
  }
}

GET /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id

Retrieve a list of all deployments in a given environment.

Required
cluster_id string	The id of the cluster in which to list the deployments.

Attributes
id string	The id of the deployment
metadata object	The metadata of the deployment
images object	The container images within a deployment
spec object	The specification used to create and run the deployment
readyRatio object	The ready replicas to total replicas ratio of this deployment set
deploymentStatus object	The status information of the deployment

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a deployment

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/coredns/kube-system?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "coredns/kube-system",
    "deploymentStatus": "Progressing",
    "readyRatio": "2/2",
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id

Retrieve a deployment and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the deployment.

Attributes
id string	The id of the deployment
metadata object	The metadata of the deployment
images object	The container images within a deployment
spec object	The specification used to create and run the deployment
readyRatio object	The ready replicas to total replicas ratio of this deployment set
deploymentStatus object	The status information of the deployment

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a deployment

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "api-test-deployment-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "nginx"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id

Create a deployment in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the deployment.
metadata object	The metadata of the deployment.
metadata.name string	The name of the deployment.
spec object	The specification used to replace and run the deployment.
spec.selector object	The label query over the deployment's set of resources.
spec.template object	The data a deployment's pod should have when replaced.
spec.spec object	The specification used to replace and run the pod(s) within the deployment.

Optional Attributes
metadata.namespace string	The namespace in which the deployment is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a deployment.

Return value:

Attributes
taskId string	The id corresponding to the replace deployment task.
taskStatus string	The status of the operation.

Replace a deployment

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/deployment-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "deployment-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "nginx"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/deployments/:id

Replace a deployment in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the deployment.
metadata object	The metadata of the deployment.
metadata.name string	The name of the deployment.
spec object	The specification used to create and run the deployment.
spec.selector object	The label query over the deployment's set of resources.
spec.template object	The data a deployment's pod should have when created.
spec.spec object	The specification used to create and run the pod(s) within the deployment.

Optional Attributes
metadata.namespace string	The namespace in which the deployment is created.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a deployment.

Return value:

Attributes
taskId string	The id corresponding to the create deployment task.
taskStatus string	The status of the operation.

Delete a deployment

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/dex/auth?cluster_id=a_cluster_id?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id

Delete a deployment from a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to list the deployments.

Return value:

Attributes
taskId string	The id corresponding to the delete deployment task.
taskStatus string	The status of the operation.

Daemon Sets

List daemon sets

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "kube-proxy/kube-system",
      "readyRatio": "3/3",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 5
  }
}

GET /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id

Retrieve a list of all daemon sets in a given environment.

Required
cluster_id string	The id of the cluster in which to list the daemon sets.

Attributes
id string	The id of the daemon set
metadata object	The metadata of the daemon set
spec object	The specification used to create and run the daemon set
status object	The status information of the daemon set

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a daemon set

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/test-aerospike/auth?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "kube-proxy/kube-system",
    "readyRatio": "3/3",
    "apiVersion": "apps/v1",
    "kind": "DaemonSet",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id

Retrieve a daemon set and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the daemon set.

Attributes
id string	The id of the daemon set
metadata object	The metadata of the daemon set
spec object	The specification used to create and run the daemon set
status object	The status information of the daemon set

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a daemon set

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "metadata": {
    "name": "daemonset-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "name": "fluentd-elasticsearch"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "fluentd-elasticsearch"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "fluentd-elasticsearch",
            "image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id

Create a daemon set in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to get the daemon set.
apiVersion string	The api version (versioned schema) of the daemon set
metadata object	The metadata of the daemon set
metadata.name string	The name of the daemon set
spec object	The specification used to create and run the daemon set
spec.selector object	The label query over the daemon set's resources
spec.template object	The data a daemon set's pod should have when created
spec.spec object	The specification used to create and run the pod(s) within the daemon set

Optional Attributes
metadata.namespace string	The namespace in which the daemon set is created
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a daemon set

Return value:

Attributes
taskId string	The id corresponding to the create daemon set task.
taskStatus string	The status of the operation.

Replace a daemon set

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/daemonset-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "DaemonSet",
  "metadata": {
    "name": "daemonset-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "name": "fluentd-elasticsearch"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "fluentd-elasticsearch"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "fluentd-elasticsearch",
            "image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/daemonsets/:id

Replace a daemon set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the daemon set.
metadata object	The metadata of the daemon set.
metadata.name string	The name of the daemon set.
spec object	The specification used to replace and run the daemon set.
spec.selector object	The label query over the daemon set's resources.
spec.template object	The data a daemon set's pod should have when replaced.
spec.spec object	The specification used to create and run the pod(s) within the daemon set.

Optional Attributes
metadata.namespace string	The namespace in which the daemon set is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a daemon set.

Return value:

Attributes
taskId string	The id corresponding to the replace daemon set task.
taskStatus string	The status of the operation.

Delete a daemon set

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/nginx-ingress-controller/ingress-nginx?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id

Delete a daemon set from a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to get the daemon set.

Return value:

Attributes
taskId string	The id corresponding to the delete daemon set task.
taskStatus string	The status of the operation.

Stateful Sets

List stateful sets

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "test-aerospike/auth",
      "images": ["aerospike/aerospike-server:4.5.0.5"],
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 4
  }
}

GET /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id

Retrieve a list of all stateful sets in a given environment.

Required
cluster_id string	The id of the cluster in which to list the stateful sets.

Attributes
id string	The id of the stateful set
metadata object	The metadata of the stateful set
spec object	The specification used to create and run the stateful set
status object	The status information of the stateful set

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a stateful set

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/test-aerospike/auth?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "test-aerospike/auth",
    "replicaRatio": "1 / 1",
    "images": ["aerospike/aerospike-server:4.5.0.5"],
    "apiVersion": "apps/v1",
    "kind": "StatefulSet",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id

Retrieve a stateful set and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the stateful set.

Attributes
id string	The id of the stateful set
metadata object	The metadata of the stateful set
spec object	The specification used to create and run the stateful set
status object	The status information of the stateful set

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a stateful set

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind":"StatefulSet",
  "metadata": {
    "name": "stateful-set-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "k8s.gcr.io/nginx-slim:0.8"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id

Create a stateful set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the stateful set
metadata object	The metadata of the stateful set
metadata.name string	The name of the stateful set
spec object	The specification used to create and run the stateful set
spec.selector object	The label query over the stateful set's resources
spec.template object	The data a stateful set's pod should have when created
spec.spec object	The specification used to create and run the pod(s) within the stateful set

Optional Attributes
metadata.namespace string	The namespace in which the stateful set is created
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a stateful set

Return value:

Attributes
taskId string	The id corresponding to the create stateful set task.
taskStatus string	The status of the operation.

Replace a stateful set

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/stateful-set-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "StatefulSet",
  "metadata": {
    "name": "stateful-set-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "k8s.gcr.io/nginx-slim:0.8"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/statefulsets/:id

Replace a stateful set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the stateful set.
metadata object	The metadata of the stateful set.
metadata.name string	The name of the stateful set.
spec object	The specification used to replaced and run the stateful set.
spec.selector object	The label query over the stateful set's of resources.
spec.template object	The data a stateful set's pod should have when replaced.
spec.spec object	The specification used to replace and run the pod(s) within the stateful set.

Optional Attributes
metadata.namespace string	The namespace in which the stateful set is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a stateful set.

Return value:

Attributes
taskId string	The id corresponding to the replace stateful set task.
taskStatus string	The status of the operation.

Delete a stateful set

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/my-aerospike/default"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id

Delete a stateful set from a given environment.

Attributes
taskId string	The id corresponding to the delete stateful set task.
taskStatus string	The status of the operation.

Networking (k8s)

Services

List services

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "alaintest-aerospike/default",
      "ports": ["3000/TCP", "3002/TCP"],
      "type": "ClusterIP",
      "metadata": {},
      "spec": {},
      "status": {
        "loadBalancer": {}
      }
    },
    {
      "id": "alertmanager-operated/monitoring",
      "ports": ["9093/TCP", "9094/TCP", "9094/UDP"],
      "type": "NodePort",
      "apiVersion": "v1",
      "kind": "Service",
      "metadata": {},
      "spec": {},
      "status": {
        "loadBalancer": {}
      }
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/services?cluster_id=:cluster_id

Retrieve a list of all services in a given environment. | Required |   | | -------------------------- | -------------------------------------------------- | | cluster_id
string | The id of the cluster in which to get the service. |

Attributes
id string	The id of the service
metadata object	The metadata of the service
metadata.name string	The name of the service
metadata.namespace string	The namespace in which the service is created
metadata.uid object	The UUID of the service
type object	The container images within a service
ports object	The list of ports that are exposed by this service
spec object	The attributes that a user creates on a service
spec.selector object	The keys and values corresponding to pod labels, used to determine where service traffic will be routed

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a service

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/test-aerospike/auth?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "test-aerospike/auth",
    "ports": ["3000/TCP", "3002/TCP"],
    "type": "ClusterIP",
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {},
    "spec": {},
    "status": {
      "loadBalancer": {}
    }
  }
}

GET /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Retrieve a service and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Attributes
id string	The id of the service
metadata object	The metadata of the service
metadata.name string	The name of the service
metadata.namespace string	The namespace in which the service is created
metadata.uid object	The UUID of the service
type object	The container images within a service
ports object	The list of ports that are exposed by this service
spec object	The attributes that a user creates on a service
spec.selector object	The keys and values corresponding to pod labels, used to determine where service traffic will be routed

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a service

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Service",
  "metadata": {
    "name": "service-name",
    "namespace": "default"
  },
  "spec": {
    "ports": [
      {
        "port": 3000,
        "protocol": "TCP"
      }
    ],
    "type": "ClusterIP"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Create a service in a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Required Attributes
apiVersion string	The api version (versioned schema) of the service.
metadata object	The metadata of the service.
metadata.name string	The name of the service.
spec object	The specification used to create and run the service.
spec.selector object	The label query over the service's set of resources.
spec.ports object	The list of ports that are exposed by this service.
spec.type object	The type of service (ClusterIP, NodePort, ExternalName or LoadBalancer)

Optional Attributes
metadata.namespace string	The namespace in which the service is created.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a service.

Return value:

Attributes
taskId string	The id corresponding to the create service task.
taskStatus string	The status of the operation.

Replace a service

curl -X PUT </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/service-name/default?cluster_id=test-cluster"

Request body example:

{
    "type": "LoadBalancer",
    "ports": [
        "4000/TCP"
    ],
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {
        "creationTimestamp": "2020-08-13T11:05:00.000-04:00",
        "name": "service-name",
        "namespace": "default",
        "resourceVersion": "170742452",
        "selfLink": "/api/v1/namespaces/default/services/service-name",
        "uid": "a84c8fea-f9d9-47ab-8e58-37059e9f18bd"
    },
    "spec": {
        "clusterIP": "10.245.44.45",
        "externalTrafficPolicy": "Cluster",
        "ports": [
            {
                "nodePort": 31167,
                "port": 3000,
                "protocol": "TCP",
                "targetPort": 306
            }
        ],
        "sessionAffinity": "ClientIP",
        "sessionAffinityConfig": {
            "clientIP": {
                "timeoutSeconds": 10555
            }
        },
        "type": "LoadBalancer"
    },
    "status": {
        "loadBalancer": {}
    }
}

PUT /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Replace a service in a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Required Attributes
apiVersion string	The api version (versioned schema) of the service.
metadata object	The metadata of the service.
metadata.name string	The name of the service.
spec object	The specification used to create and run the service.

Return value:

Attributes
taskId string	The id corresponding to the replace service task.
taskStatus string	The status of the operation.

Delete a service

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/test-service/default?cluster_id=test-cluster"

DELETE /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Delete a service from a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Attributes
taskId string	The id corresponding to the delete service task.
taskStatus string	The status of the operation.

Ingresses

List ingresses

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "cloudmc/cmc-stg",
      "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
      "service": {
        "port": "8080",
        "name": "cloudmc"
      },
      "metadata": {
        "annotations": {},
        "creationTimestamp": "2019-07-11T10:00:18.000-04:00",
        "generation": 10,
        "name": "cloudmc",
        "namespace": "cmc-stg",
        "resourceVersion": "143213903",
        "selfLink": "/apis/extensions/v1beta1/namespaces/cmc-stg/ingresses/cloudmc",
        "uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
      },
      "spec": {
        "rules": [],
        "tls": []
      },
      "status": {
        "loadBalancer": {}
      }
    },
    {
      "id": "cm-acme-http-solver-75png/auth",
      "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
      "service": {
        "port": "8089",
        "name": "cm-acme-http-solver-2x5gv"
      },
      "metadata": {
        "annotations": {},
        "creationTimestamp": "2020-06-24T11:00:49.000-04:00",
        "generateName": "cm-acme-http-solver-",
        "generation": 1,
        "labels": {
          "acme.cert-manager.io/http-domain": "1965164889",
          "acme.cert-manager.io/http-token": "820448657",
          "acme.cert-manager.io/http01-solver": "true"
        },
        "name": "cm-acme-http-solver-75png",
        "namespace": "auth",
        "ownerReferences": [],
        "resourceVersion": "143213968",
        "selfLink": "/apis/extensions/v1beta1/namespaces/auth/ingresses/cm-acme-http-solver-75png",
        "uid": "48720f48-f2bc-45fc-95c5-60cae8ffe11e"
      },
      "spec": {
        "rules": []
      },
      "status": {
        "loadBalancer": {}
      }
    }
  ]
}

GET /services/:service_code/:environment_name/ingresses?cluster_id=:cluster_id

Retrieve a list of all ingresses in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Attributes
id string	The id of the ingress
endpoint string	The endpoint of the ingress
service object	The service associated with the ingress
service.port string	The port of the service associated with the ingress
service.name string	The name of the service associated with the ingress
metadata object	The metadata of the ingress
metadata.name string	The name of the ingress
metadata.namespace string	The namespace in which the ingress is created
metadata.labels object	The labels associated with the ingress
metadata.uid object	The UUID of the ingress
spec object	The attributes that a user specifies for an ingress

Note that the list is not complete, since it is refering to the kubernetes api details.

Get an ingress

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/cloudmc/cmc-stg?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cloudmc/cmc-stg",
    "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
    "service": {
      "port": "8080",
      "name": "cloudmc"
    },
    "metadata": {
      "annotations": {},
      "creationTimestamp": "2019-07-11T10:00:18.000-04:00",
      "generation": 10,
      "name": "cloudmc",
      "namespace": "cmc-stg",
      "resourceVersion": "143213903",
      "selfLink": "/apis/extensions/v1beta1/namespaces/cmc-stg/ingresses/cloudmc",
      "uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
    },
    "spec": {
      "rules": [],
      "tls": []
    },
    "status": {
      "loadBalancer": {}
    }
  }
}

GET /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Retrieve an ingress and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Attributes
id string	The id of the ingress
endpoint string	The endpoint of the ingress
service object	The service associated with the ingress
service.port string	The port of the service associated with the ingress
service.name string	The name of the service associated with the ingress
metadata object	The metadata of the ingress
metadata.name string	The name of the ingress
metadata.namespace string	The namespace in which the ingress is created
metadata.labels object	The labels associated with the ingress
metadata.uid object	The UUID of the ingress
spec object	The attributes that a user specifies for an ingress

Note that the list is not complete, since it is refering to the kubernetes api details.

Create an ingress

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses"
  Content-Type: application/json
  {
  "apiVersion": "networking.k8s.io/v1beta1",
  "kind": "Ingress",
  "metadata": {
    "name": "ingress-name",
    "namespace": "default",
    "annotations": {
      "nginx.ingress.kubernetes.io/rewrite-target": "/"
    }
  },
  "spec": {
    "rules": [
      {
        "hostname": "endpoint.com",
        "http": {
          "paths": [
            {
              "path": "/testpath",
              "pathType": "Prefix",
              "backend": {
                "serviceName": "test",
                "servicePort": 80
              }
            }
          ]
        }
      }
    ]
  }
}

POST /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Create an ingress in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Required Attributes
apiVersion string	The api version (versioned schema) of the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
spec object	The specification used to create and run the ingress.
spec.rules object	The list of host rules used to configure the ingress.

Optional Attributes
metadata.namespace string	The namespace in which the ingress is created.

Return value:

Attributes
taskId string	The id corresponding to the create ingress task.
taskStatus string	The status of the operation.

Replace an ingress

curl -X PUT </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/ingress-name/default?cluster_id=test-cluster"

Request body example:

{
  "endpoint": "http://my-endpoint.com",
  "service": {
    "port": "6556",
    "name": "test"
  },
  "apiVersion": "extensions/v1beta1",
  "kind": "Ingress",
  "metadata": {
    "creationTimestamp": "2020-08-13T14:13:42.000-04:00",
    "generation": 3,
    "name": "ingress-name",
    "namespace": "default",
    "resourceVersion": "170302224",
    "selfLink": "/apis/extensions/v1beta1/namespaces/default/ingresses/ingress-name",
    "uid": "c67e6a6a-2b07-4976-8b3d-2ec9fd91ae5d"
  },
  "spec": {
    "rules": [
      {
        "host": "my-endpoint.com",
        "http": {
          "paths": [
            {
              "backend": {
                "serviceName": "test",
                "servicePort": 6556
              },
              "path": "/testpath"
            }
          ]
        }
      }
    ]
  },
  "status": {
    "loadBalancer": {
      "ingress": [
        {
          "hostname": "hostname-worker-01"
        },
        {
          "hostname": "hostname-worker-02"
        },
        {
          "hostname": "hostname-worker-03"
        },
        {
          "hostname": "hostname-worker-04"
        }
      ]
    }
  }
}

PUT /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Replace an ingress in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Required Attributes
apiVersion string	The api version (versioned schema) of the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
spec object	The specification used to create and run the ingress.

Return value:

Attributes
taskId string	The id corresponding to the replace ingress task.
taskStatus string	The status of the operation.

Delete an ingress

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/test-ingress/default?cluster_id=test-cluster"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Delete an ingress from a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Return value:

Attributes
taskId string	The id corresponding to the delete ingress task.
taskStatus string	The status of the operation.

Configuration

Config Maps

List config maps

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "coredns/kube-system",
      "data": {
        "Corefile": ".:53 {\n    errors\n    health\n    kubernetes cluster.local in-addr.arpa ip6.arpa {\n      pods insecure\n      upstream\n      fallthrough in-addr.arpa ip6.arpa\n    }\n    prometheus :9153\n    forward . /etc/resolv.conf\n    cache 30\n    loop\n    reload\n    loadbalance\n    import custom/.override\n}\nimport custom/.server\n"
      },
      "metadata": {}
    }
  ],
  "metadata": {
    "recordCount": 4
  }
}

GET /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id

Retrieve a list of all config maps in a given environment.

Required
cluster_id string	The id of the cluster in which to list the config maps.

Attributes
id string	The id of the config map.
apiVersion string	The API version used to retrieve this config map.
metadata object	The metadata of the config map.

Get a config map

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/coredns/kube-system?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "coredns/kube-system",
    "apiVersion": "v1",
    "data": {
      "Corefile": ".:53 {\n    errors\n    health\n    kubernetes cluster.local in-addr.arpa ip6.arpa {\n      pods insecure\n      upstream\n      fallthrough in-addr.arpa ip6.arpa\n    }\n    prometheus :9153\n    forward . /etc/resolv.conf\n    cache 30\n    loop\n    reload\n    loadbalance\n    import custom/.override\n}\nimport custom/.server\n"
    },
    "kind": "ConfigMap",
    "metadata": {}
  }
}

GET /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id

Retrieve a config map and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the config map.

Attributes
id string	The id of the config map.
apiVersion string	The API version used to retrieve this config map.
metadata object	The metadata of the config map.

Create a config map

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "game-demo"
  },
  "data": {
    "player_initial_lives": "3",
    "ui_properties_file_name": "user-interface.properties",
    "game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
    "user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id

Create a config map in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to create the config map.
apiVersion string	The api version (versioned schema) of the config map.
metadata object	The metadata of the config map.
metadata.name string	The name of the config map.
data object	The non-confidential data (in key-value pairs) stored in the config map.

Optional Attributes
metadata.namespace string	The namespace in which the config map is created

Return value:

Attributes
taskId string	The id corresponding to the create config maps task.
taskStatus string	The status of the operation.

Replace a config map

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/game-demo/default?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "game-demo",
    "namespace": "default"
  },
  "data": {
    "player_initial_lives": "5",
    "ui_properties_file_name": "user-interface.properties",
    "game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
    "user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id

Replace a config map in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to replace the config map.
apiVersion string	The api version (versioned schema) of the config map.
metadata object	The metadata of the config map.
metadata.name string	The name of the config map.
data object	The non-confidential data (in key-value pairs) stored in the config map.

Optional Attributes
metadata.namespace string	The namespace in which the config map is replaced.

Return value:

Attributes
taskId string	The id corresponding to the replace config maps task.
taskStatus string	The status of the operation.

Delete a config map

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id

Delete a config map from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the config map.

Attributes
taskId string	The id corresponding to the delete config map task.
taskStatus string	The status of the operation.

Secrets

List secrets

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "default-token-xxxmt/default",
      "apiVersion": "v1",
      "encodedData": {
        "ca.crt": "LS0tLS...",
        "namespace": "a3ViZS1zeXN0ZW0=",
        "token": "ZXlKa..."
      },
      "kind": "Secret",
      "metadata": {},
      "type": "kubernetes.io/service-account-token"
    }
  ],
  "metadata": {
    "recordCount": 100
  }
}

GET /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id

Retrieve a list of all secrets in a given environment.

Required
cluster_id string	The id of the cluster in which to list the secrets.

Attributes
id string	The id of the secret.
apiVersion string	The API version used to retrieve the secret.
encodedData object	The base64 encoded data stored in the secret.
metadata object	The metadata of the secret.
type string	A string used to facilitate programmatic handling of a secret's data.

Get a secret

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "default-token-xxxmt/default",
    "apiVersion": "v1",
    "encodedData": {
      "ca.crt": "LS0tLS...",
      "namespace": "a3ViZS1zeXN0ZW0=",
      "token": "ZXlKa..."
    },
    "kind": "Secret",
    "metadata": {},
    "type": "kubernetes.io/service-account-token"
  }
}

GET /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id

Retrieve a secret and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the secret.

Attributes
id string	The id of the secret.
apiVersion string	The API version used to retrieve the secret.
encodedData object	The base64 encoded data stored in the secret.
metadata object	The metadata of the secret.
type string	A string used to facilitate programmatic handling of a secret's data.

Create a secret

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "stringData": {
    "username": "my-username",
    "password": "my-password"
  }
}


# OR

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "encodedData": {
    "username": "YWRtaW4=",
    "password": "MWYyZDFlMmU2N2Rm"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id

Create a secret in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to create the secret.
apiVersion string	The api version (versioned schema) of the secret.
metadata object	The metadata of the secret.
metadata.name string	The name of the secret.

One of the following two attributes is also required.

Attributes
encodedData object	The base64 encoded data stored in the secret.
stringData object	The non-base64 encoded data to be encoded when the secret is created.

Optional Attributes
metadata.namespace string	The namespace in which the secret is created

Return value:

Attributes
taskId string	The id corresponding to the create secret task.
taskStatus string	The status of the operation.

Replace a secret

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/my-secret/shhh"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "stringData": {
    "username": "my-username",
    "password": "my-new-password"
  }
}


# OR

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret",
    "namespace": "shhh"
  },
  "type": "Opaque",
  "encodedData": {
    "username": "YWRtaW4=",
    "password": "MWYyFZDlMmU2N2Rm"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id

Replace a secret in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to replace the secret.
apiVersion string	The api version (versioned schema) of the secret.
metadata object	The metadata of the secret.
metadata.name string	The name of the secret.

One of the following two attributes is also required.

Attributes
encodedData object	The base64 encoded data stored in the secret.
stringData object	The non-base64 encoded data to be encoded when the secret is replaced.

Optional Attributes
metadata.namespace string	The namespace in which the secret is replaced

Return value:

Attributes
taskId string	The id corresponding to the replace secret task.
taskStatus string	The status of the operation.

Delete a secret

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id

Delete a secret from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the secret.

Attributes
taskId string	The id corresponding to the delete secret task.
taskStatus string	The status of the operation.

Storage (k8s)

Storage Classes

List storage classes

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "rook-ceph-block",
      "isDefault": true,
      "allowVolumeExpansion": true,
      "metadata": {
        "annotations": {
          "storageclass.kubernetes.io/is-default-class": "true"
        },
        "creationTimestamp": "2020-04-20T16:08:54.000-04:00",
        "name": "rook-ceph-block",
        "resourceVersion": "107033002",
        "selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
        "uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
      },
      "parameters": {
        "clusterID": "rook-ceph",
        "csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
        "csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
        "csi.storage.k8s.io/fstype": "ext4",
        "csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
        "csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
        "csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
        "csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
        "imageFeatures": "layering",
        "imageFormat": "2",
        "pool": "replicapool"
      },
      "provisioner": "rook-ceph.rbd.csi.ceph.com",
      "reclaimPolicy": "Delete",
      "volumeBindingMode": "Immediate"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id

Retrieve a list of all storage classes in a given environment.

Required
cluster_id string	The id of the cluster in which to list the storage classes.

Attributes
id string	The id of the storage class. This is the name of the resource.
isDefault boolean	Whether or not the storage class is the default one.
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.
metadata object	The metadata of the storage class.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
provisioner string	The provisioner for the storage class.
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Get a storage class

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "rook-ceph-block",
    "isDefault": true,
    "allowVolumeExpansion": true,
    "metadata": {
      "annotations": {
        "storageclass.kubernetes.io/is-default-class": "true"
      },
      "creationTimestamp": "2020-04-20T16:08:54.000-04:00",
      "name": "rook-ceph-block",
      "resourceVersion": "107033002",
      "selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
      "uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
    },
    "parameters": {
      "clusterID": "rook-ceph",
      "csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
      "csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
      "csi.storage.k8s.io/fstype": "ext4",
      "csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
      "csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
      "csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
      "csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
      "imageFeatures": "layering",
      "imageFormat": "2",
      "pool": "replicapool"
    },
    "provisioner": "rook-ceph.rbd.csi.ceph.com",
    "reclaimPolicy": "Delete",
    "volumeBindingMode": "Immediate"
  }
}

GET /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id

Retrieve a storage class and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to list the storage classes.

Attributes
id string	The id of the storage class. This is the name of the resource
isDefault boolean	Whether or not the storage class is the default one
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.
metadata object	The metadata of the storage class.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
provisioner string	The provisioner for the storage class
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Create a storage class

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "storage.k8s.io/v1",
  "kind": "StorageClass",
  "metadata": {
    "name": "local-storage-name"
  },
  "provisioner": "kubernetes.io/no-provisioner",
  "volumeBindingMode": "WaitForFirstConsumer"
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id

Create a storage class in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the storage class.
metadata object	The metadata of the storage class.
metadata.name string	The name of the storage class.
provisioner string	The provisioner for the storage class
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Optional Attributes
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.

Return value:

Attributes
taskId string	The id corresponding to the create stateful set task.
taskStatus string	The status of the operation.

Replace a storage class

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
    "apiVersion": "storage.k8s.io/v1",
    "metadata": {
        "name": "hostpath"
    },
    "provisioner": "docker.io/hostpath"
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id

Replace a storage class in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the storage class.
metadata object	The metadata of the storage class.
metadata.name string	The name of the storage class.
provisioner object	The type of provisioner.

Optional Attributes
reclaimPolicy string	Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace storage class task.
taskStatus string	The status of the operation.

Delete a storage class

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id

Delete a storage class from a given environment.

Required
cluster_id string	The id of the cluster in which to get the storage class.

Attributes
taskId string	The id corresponding to the delete storage class task.
taskStatus string	The status of the operation.

Persistent volumes

List persistent volumes

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
      "metadata": {
        "annotations": {
          "pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
        },
        "creationTimestamp": "2020-07-03T09:12:17.000-04:00",
        "finalizers": ["kubernetes.io/pv-protection"],
        "name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
        "resourceVersion": "147569183",
        "selfLink": "/api/v1/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
        "uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
      },
      "spec": {
        "accessModes": ["ReadWriteOnce"],
        "capacity": {
          "storage": "8Gi"
        },
        "claimRef": {
          "apiVersion": "v1",
          "kind": "PersistentVolumeClaim",
          "name": "data-cmc-cluster-zookeeper-1",
          "namespace": "cmc-kafka",
          "resourceVersion": "147569124",
          "uid": "05097a93-120d-45d2-aaab-0f273849fccd"
        },
        "csi": {
          "driver": "rook-ceph.rbd.csi.ceph.com",
          "fsType": "ext4",
          "nodeStageSecretRef": {
            "name": "rook-csi-rbd-node",
            "namespace": "rook-ceph"
          },
          "volumeAttributes": {
            "clusterID": "rook-ceph",
            "imageFeatures": "layering",
            "imageFormat": "2",
            "pool": "replicapool",
            "storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
          },
          "volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
        },
        "persistentVolumeReclaimPolicy": "Delete",
        "storageClassName": "rook-ceph-block",
        "volumeMode": "Filesystem"
      },
      "status": {
        "phase": "Bound"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/persistentvolumes?cluster_id=:cluster_id

Retrieve a list of all persistent volumes in a given environment.

Required
cluster_id string	The id of the cluster in which to list the persistent volumes.

Attributes
id string	The id of the persistent volume. This is the name of the resource.
metadata object	The metadata of the persistent volume.
spec object	The specification of the persistent volume.
spec.accessModes string	The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.capacity.storage string	Storage capacity of the persistent volume.
spec.persistentVolumeReclaimPolicy string	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Get a persistent volume

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "id": "pvc-05097a93-120d-45d2",
  "metadata": {
    "annotations": {
      "pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
    },
    "creationTimestamp": "2020-07-03T09:12:17.000-04:00",
    "finalizers": ["kubernetes.io/pv-protection"],
    "name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
    "resourceVersion": "147569183",
    "selfLink": "/api/v1/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
    "uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
  },
  "spec": {
    "accessModes": ["ReadWriteOnce"],
    "capacity": {
      "storage": "8Gi"
    },
    "claimRef": {
      "apiVersion": "v1",
      "kind": "PersistentVolumeClaim",
      "name": "data-cmc-cluster-zookeeper-1",
      "namespace": "cmc-kafka",
      "resourceVersion": "147569124",
      "uid": "05097a93-120d-45d2-aaab-0f273849fccd"
    },
    "csi": {
      "driver": "rook-ceph.rbd.csi.ceph.com",
      "fsType": "ext4",
      "nodeStageSecretRef": {
        "name": "rook-csi-rbd-node",
        "namespace": "rook-ceph"
      },
      "volumeAttributes": {
        "clusterID": "rook-ceph",
        "imageFeatures": "layering",
        "imageFormat": "2",
        "pool": "replicapool",
        "storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
      },
      "volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
    },
    "persistentVolumeReclaimPolicy": "Delete",
    "storageClassName": "rook-ceph-block",
    "volumeMode": "Filesystem"
  },
  "status": {
    "phase": "Bound"
  }
}

GET /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id

Retrieve a persistent volume and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the persistent volume.

Attributes
id string	The id of the persistent volume. This is the name of the resource.
metadata object	The metadata of the persistent volume.
spec object	The specification of the persistent volume.
spec.accessModes string	The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.capacity.storage string	Storage capacity of the persistent volume.
spec.persistentVolumeReclaimPolicy string	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Create a persistent volume

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes"
  Content-Type: application/json
   {
      "apiVersion": "v1",
      "metadata": {
         "name": "small-pvc",
         "namespace": "default"
      },
      "spec": {
         "accessModes": [
            "ReadWriteOnce"
         ],
         "resources": {
            "requests": {
               "storage": "10G"
            }
         }
      }
   }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/persistentvolumes

Create a persistent volume in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the persistent volume.
metadata object	The metadata of the persistent volume.
metadata.name string	The name of the persistent volume.
spec object	The spec for the persistent volume.
spec.accessModes array	A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany.
spec.capacity.storage string	Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.
spec.<VOLUME_TYPE> object	Volume types are identified by name and what volume types are supported differ heavily by Kubernetes deployment. The contents of the object also depend on the volume type. Examples of common volumes types are nfs, hostPath, or local.

Optional Attributes
metadata.namespace string	The namespace in which the pod is created, if not specified will create the persistent volume in default.
spec.storageClassName string	Storage class associated to the volume.
spec.claimRef array	The name of the PersistentVolumeClaim associated to the persistent volume.
spec.mountOptions array	Mount options for when a Persistent Volume is mounted on a node.
spec.nodeAffinity array	Defines constraints that limit what nodes this volume can be accessed from.
spec.persistentVolumeReclaimPolicy array	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.volumeMode array	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Return value:

Attributes
taskId string	The id corresponding to the create persistent volume task.
taskStatus string	The status of the operation.

Replace a persistent volume

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/my-persistent-volume?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "kind": "PersistentVolume",
    "metadata": {
        "annotations": {
            "key": "value"
        },
        "name": "persistentvolumes-name"
    },
    "spec": {
        "accessModes": [
            "ReadWriteMany"
        ],
        "capacity": {
            "storage": "2Gi"
        },
        "claimRef": {
            "apiVersion": "v1",
            "kind": "PersistentVolumeClaim",
            "name": "pv-claim-name",
            "namespace": "default",
            "resourceVersion": "259087",
            "uid": "11957feb-1acc-4c7e-911e-f77d5d7be5ac"
        },
        "hostPath": {
            "path": "/etc/path"
        },
        "persistentVolumeReclaimPolicy": "Retain",
        "storageClassName": "standard",
        "volumeMode": "Filesystem"
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=a_cluster_id

Replace a persistent volume in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the volume.
metadata object	The metadata of the volume.
metadata.name string	The name of the volume.
spec object	The specification used to replace and run the volume.
spec.accessModes string	The desired access modes the volume should have.
spec.capacity.storage string	The size of the claim.
spec.hostPath.path string	The path of the directory on the host.

Optional Attributes
metadata.annotations string	Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.
spec.claimRef string	part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound.
spec.persistentVolumeReclaimPolicy string	What happens to a persistent volume when released from its claim.
spec.storageClassName string	Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass.
spec.volumeMode string	Defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace volume task.
taskStatus string	The status of the operation.

Delete a persistent volume

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id

Delete a perstent volume from a given environment.

Required
cluster_id string	The id of the cluster in which to get the perstent volume.

Attributes
taskId string	The id corresponding to the delete persistent volume task.
taskStatus string	The status of the operation.

Persistent Volume Claims

List persistent volume claims

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "cmc-staging-mysql/cmc-stg",
      "metadata": {
        "annotations": {
          "pv.kubernetes.io/bind-completed": "yes",
          "pv.kubernetes.io/bound-by-controller": "yes",
          "volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
        },
        "creationTimestamp": "2020-04-27T12:01:22.000-04:00",
        "finalizers": ["kubernetes.io/pvc-protection"],
        "labels": {
          "app": "cmc-staging-mysql",
          "chart": "mysql-0.4.5",
          "heritage": "Helm",
          "release": "cmc-staging"
        },
        "name": "cmc-staging-mysql",
        "namespace": "cmc-stg",
        "resourceVersion": "111495311",
        "selfLink": "/api/v1/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
        "uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
      },
      "spec": {
        "accessModes": ["ReadWriteOnce"],
        "resources": {
          "requests": {
            "storage": "8Gi"
          }
        },
        "storageClassName": "rook-ceph-block",
        "volumeMode": "Filesystem",
        "volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
      },
      "status": {
        "accessModes": ["ReadWriteOnce"],
        "capacity": {
          "storage": "8Gi"
        },
        "phase": "Bound"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id

Retrieve a list of all persistent volume claims in a given environment.

Required
cluster_id string	The id of the cluster in which to list the persistent volume claims.

Attributes
id string	The id of the persistent volume claim. This is the name and namespace of the resource.
metadata object	The metadata of the persistent volume claim.
spec object	The specification of the persistent volume claim.
spec.accessModes string	The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.resources.requests.storage string	The requested storage capacity of the persistent volume.
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status object	The status of the persistent volume claim.
status.phase string	The claim is in one of the following phases: Pending, Bound, Lost or Terminating.
status.accessModes string	The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
status.capacity.storage string	The allocated storage capacity.

Get a persistent volume claim

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cmc-staging-mysql/cmc-stg",
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
      "annotations": {
        "pv.kubernetes.io/bind-completed": "yes",
        "pv.kubernetes.io/bound-by-controller": "yes",
        "volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
      },
      "creationTimestamp": "2020-04-27T12:01:22.000-04:00",
      "finalizers": ["kubernetes.io/pvc-protection"],
      "labels": {
        "app": "cmc-staging-mysql",
        "chart": "mysql-0.4.5",
        "heritage": "Helm",
        "release": "cmc-staging"
      },
      "name": "cmc-staging-mysql",
      "namespace": "cmc-stg",
      "resourceVersion": "111495311",
      "selfLink": "/api/v1/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
      "uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
    },
    "spec": {
      "accessModes": ["ReadWriteOnce"],
      "resources": {
        "requests": {
          "storage": "8Gi"
        }
      },
      "storageClassName": "rook-ceph-block",
      "volumeMode": "Filesystem",
      "volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
    },
    "status": {
      "accessModes": ["ReadWriteOnce"],
      "capacity": {
        "storage": "8Gi"
      },
      "phase": "Bound"
    }
  }
}

GET /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id

Retrieve a persistent volume claim and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the persistent volume claim.

Attributes
id string	The id of the persistent volume claim. This is the name and namespace of the resource.
metadata object	The metadata of the persistent volume claim.
spec object	The specification of the persistent volume claim.
spec.accessModes string	The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.resources.requests.storage string	The requested storage capacity of the persistent volume.
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status object	The status of the persistent volume claim.
status.phase string	The claim is in one of the following phases: Pending, Bound, Lost or Terminating.
status.accessModes string	The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
status.capacity.storage string	The allocated storage capacity.

Create a persistent volume claim

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
  Content-Type: application/json
{
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
        "name": "small-pvc",
        "namespace": "default"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "resources": {
            "requests": {
                "storage": "10G"
            }
        }
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id

Create a persistent volume claim in a given environment.

Required
cluster_id string	The id of the cluster in which to list the persistent volume claims.

Required Attributes
apiVersion string	The api version (versioned schema) of the persistent volume claim.
metadata object	The metadata of the persistent volume claim.
metadata.name string	The name of the persistent volume claim.
spec object	The spec for the persistent volume claim.
spec.accessModes array	A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany.
spec.resources.requests.storage string	Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.

Optional Attributes
metadata.namespace string	The namespace in which the pod is created, if not specified will create the claim in default.
spec.storageClassName string	The storage class for the persistent volume claim, will use the default if not specified.
spec.resources.limits object	Limits describe the maximum number of storage resources allowed.

Return value:

Attributes
taskId string	The id corresponding to the create persistent volume claim task.
taskStatus string	The status of the operation.

Replace a persistent volume claim

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/my-persistent-volume-claim/default?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
    "id": "pv-claim-name/default",
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
        "name": "pv-claim-name",
        "namespace": "default"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "resources": {
            "requests": {
                "storage": "1Gi"
            }
        },
        "storageClassName": "standard",
        "volumeName": "persistentvolumes-name",
        "dataSource": "dataSource"
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id

Replace a persistent volume claim in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the claim.
metadata object	The metadata of the claim.
metadata.name string	The name of the claim.
spec object	The specification used to replace and run the claim.
spec.accessModes string	The desired access modes the volume should have.
spec.resources.requests.storage string	The size of the claim.
spec.storageClassName string	The name of the StorageClass required by the claim.

Optional Attributes
spec.volumeName string	The binding reference to the PersistentVolume backing this claim. Only required if claim is bound.
spec.volumemode string	What type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec.
spec.dataSource string	This field can be used to specify either: an existing VolumeSnapshot object, an existing PVC or an existing custom resource/object that implements data population.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace persistent volume claim task.
taskStatus string	The status of the operation.

Delete a persistent volume claim

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id

Delete a perstent volume claim from a given environment.

Required
cluster_id string	The id of the cluster in which to get the perstent volume claim.

Attributes
taskId string	The id corresponding to the delete persistent volume claim task.
taskStatus string	The status of the operation.

Access control

Service accounts

List service accounts

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
      "metadata": {
        "name": "vpnkit-controller",
        "namespace": "kube-system",
        "selfLink": "/api/v1/namespaces/kube-system/serviceaccounts/vpnkit-controller",
        "uid": "b9afa8a8-3d64-4605-959f-12bb5c6cfba2",
        "resourceVersion": "481",
        "creationTimestamp": "2020-09-18T14:47:48Z",
        "annotations": {
          "kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ServiceAccount\",\"metadata\":{\"annotations\":{},\"name\":\"vpnkit-controller\",\"namespace\":\"kube-system\"}}\n"
        }
      },
      "secrets": [
        {
          "name": "vpnkit-controller-token-hl674"
        }
      ]
    }
  ]
}

GET /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id

Retrieve a list of all service accounts in a given environment.

Attributes
id string	The id of the service account.
metadata.annotations map	The annotations of the service account.
metadata object	The metadata of the service account.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace in which the service account is created.
metadata.uid object	The UUID of the service account.
metadata.secrets List<object>	The secrets of the service account.
secretsSize integer	The number of secrets of the service account.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a service account

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/serviceaccount-name/serviceaccount-namespace?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
            "id": "default",
            "age": "1w5d",
            "secretsSize": 1,
            "metadata": {
              "creationTimestamp": "2020-09-18T10:46:40.000-04:00",
              "name": "default",
              "namespace": "default",
              "uid": "80a0de4d-a187-44c3-b691-1481220a5817"
            },
            "secrets": [
              {
                "name": "default-token-lrth9"
              }
            ]
          },
          "fieldTransitions": {},
          "operations": []
        }

GET /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id

Retrieve a service account and all its info in a given environment.

Attributes
id string	The id of the service account.
metadata object	The metadata of the service account.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace in which the service account is created.
metadata.uid object	The UUID of the service account.
metadata.secrets List<object>	The secrets of the service account.
secretsSize integer	The number of secrets of the service account.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a service account

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "metadata": {
        "name": "service-account-name",
        "namespace": "default"
    }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id

Create a service account in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the service account.
metadata object	The metadata of the service account.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace of the service account.

Return value:

Attributes
taskId string	The id corresponding to the create service account task.
taskStatus string	The status of the operation.

Replace a service account

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/service-account-name/namespace-name?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "metadata": {
        "name": "service-account-name",
        "namespace": "namespace-name"
    }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id

Replace a service account in a given environment.

Required Attributes
metadata object	The metadata of the service account.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace of the service account.

Return value:

Attributes
taskId string	The id corresponding to the create service account task.
taskStatus string	The status of the operation.

Delete a service account

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/my-service-account/my-namespace?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id

Delete a service account from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the service account.

Attributes
taskId string	The id corresponding to the delete service account task.
taskStatus string	The status of the operation.

Roles

List (namespace) Roles

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "role-id",
            "age": "1w4d",
            "metadata": {
                "creationTimestamp": "2020-09-18T10:01:26.000-04:00",
                "name": "kubeadm:bootstrap-signer-clusterinfo",
                "namespace": "kube-public",
                "uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a46"
            },
            "rules": [
                {
                    "apiGroups": [],
                    "resourceNames": [],
                    "resources": [],
                    "verbs": []
                }
            ]
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/roles?cluster_id=:cluster_id

Retrieve a list of all roles in a given environment.

Attributes
id string	The id of the role.
metadata object	The metadata of the role.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the role.
metadata.namespace string	The namespace in which the role is created.
metadata.uid object	The UUID of the role.
rules array	The array of rules associated with this role.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a role

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/role-name/role-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "kubeadm:bootstrap-signer-clusterinfo",
        "age": "1w4d",
        "apiVersion": "rbac.authorization.k8s.io/v1",
        "kind": "Role",
        "metadata": {
            "creationTimestamp": "2020-09-18T10:01:26.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a47"
        },
        "rules": [
            {
                "apiGroups": [],
                "resourceNames": [],
                "resources": [],
                "verbs": []
            }
        ]
    }
}

GET /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id

Retrieve a role and all its info in a given environment.

Attributes
id string	The id of the role.
apiVersion string	The API version used to retrieve this role.
metadata object	The metadata of the role.
rules array	The array of rules associated with this role.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a role

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles?cluster_id=:cluster_id"
  Content-Type: application/json
  {
   "apiVersion": "rbac.authorization.k8s.io/v1",
   "kind": "Role",
   "namespace": "default",
   "name": "test-name",
   "metadata": {
      "namespace": "default",
      "name": "test-name"
   },
   "rules": [
      {
         "apiGroups": [
            ""
         ],
         "resources": [
            "resource"
         ],
         "verbs": [
            "get",
            "watch"
         ]
      }
   ]
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/roles?cluster_id=:cluster_id

Create a role in a given environment.

Attributes
id string	The id of the role.
apiVersion string	The API version used to create this role.
metadata.name string	The name of the role.
metadata.namespace string	The namespace of the role.
rules array	The array of rules associated with this role.

Return value:

Attributes
taskId string	The id corresponding to the create role task.
taskStatus string	The status of the operation.

Replace a role

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/role-name/namespace-name?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "metadata": {
        "name": "role-name",
        "namespace": "namespace-name"
    }
    "rules": [
      {
         "apiGroups": [
            ""
         ],
         "resources": [
            "resource"
         ],
         "verbs": [
            "get",
            "watch",
            "..."
         ]
      }
   ]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id

Replace a role in a given environment.

Required Attributes
metadata object	The metadata of the role.
metadata.name string	The name of the role.
metadata.namespace string	The namespace of the role.
metadata.namespace string	The namespace of the role.

Optional Attributes
rules array	The array of rules associated with this role.

Return value:

Attributes
taskId string	The id corresponding to the replace role operation.
taskStatus string	The status of the operation.

Delete a role

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id

Delete a role from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the role.

Attributes
taskId string	The id corresponding to the delete role task.
taskStatus string	The status of the operation.

Role bindings

List (namespace) role bindings

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{


"data": {
        "entity": {
          "id": "kubeadm:bootstrap-signer-clusterinfo",
          "age": "1w5d",
          "metadata": {
            "creationTimestamp": "2020-09-18T10:46:32.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
          },
          "roleRef": {
            "apiGroup": "rbac.authorization.k8s.io",
            "kind": "Role",
            "name": "kubeadm:bootstrap-signer-clusterinfo"
          },
          "subjects": [
            {
              "apiGroup": "rbac.authorization.k8s.io",
              "kind": "User",
              "name": "system:anonymous"
            }
          ]
        },
        "fieldTransitions": {},
        "operations": []
      },
}

GET /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id

Retrieve a list of all role bindings in a given environment.

Attributes
id string	The id of the role binding.
metadata object	The metadata of the role binding.
metadata.creationTimestamp string	The date of creation of the role binding as a string.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace in which the role binding is created.
metadata.uid object	The UUID of the role binding.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a role binding

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/rolebinding-name/rolebinding-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{


"data": {

"id": "kubeadm:bootstrap-signer-clusterinfo",
          "age": "1w5d",
          "metadata": {
            "creationTimestamp": "2020-09-18T10:46:32.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
          },
          "roleRef": {
            "apiGroup": "rbac.authorization.k8s.io",
            "kind": "Role",
            "name": "kubeadm:bootstrap-signer-clusterinfo"
          },
          "subjects": [
            {
              "apiGroup": "rbac.authorization.k8s.io",
              "kind": "User",
              "name": "system:anonymous"
            }
          ]
        },
        "fieldTransitions": {},
        "operations": []
      },
}

GET /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id

Retrieve a role binding and all its info in a given environment.

Attributes
id string	The id of the role binding.
apiVersion string	The API version used to retrieve this role binding.
metadata object	The metadata of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	The array of subjects associated with this role binding.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a role binding

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "kind": "Rolebinding",
    "metadata": {
        "name": "rolebinding-name",
        "namespace": "namespace-name"
    },
    "roleRef": {
        "apiGroup": "rbac.authorization.k8s.io",
        "kind": "Role",
        "name": "role-name"
    },
    "subjects": [
        {
            "kind": "ServiceAccount",
            "name": "service-account-name",
            "namespace": "service-account-namespace"
        },
        {
            "kind": "Group",
            "name": "group-name",
            "namespace": "group-namespace"
        },
        {
            "kind": "User",
            "name": "user-name",
        }


]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id

Create a role binding in a given environment.

Required Attributes
metadata object	The metadata of the role binding.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts.

Return value:

Attributes
taskId string	The id corresponding to the create role binding task.
taskStatus string	The status of the operation.

Replace a role binding

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/rolebinding-name/namespace-name?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "metadata": {
        "name": "service-account-name",
        "namespace": "namespace-name"
    },
    "roleRef": {
      "apiGroup": "",
      "kind": "Role",
      "name": "role-name"
    },
    "subjects": [
      {
        "kind": "ServiceAccount",
        "name": "default",
        "namespace": "default"
      },
      {
        "kind": "user",
        "name": "user1",
      }
    ]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id

Replace a role binding in a given environment.

Required Attributes
metadata object	The metadata of the role binding.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts.

Return value:

Attributes
taskId string	The id corresponding to the replace role binding operation.
taskStatus string	The status of the operation.

Delete a role binding

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this: json { "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b", "taskStatus": "PENDING" } DELETE /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id

Delete a role binding from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the role binding.

Attributes
taskId string	The id corresponding to the delete role binding task.
taskStatus string	The status of the operation.

Releases

List releases

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-namespace/my-cloudflare",
      "name": "my-cloudflare",
      "info": {
        "first_deployed": "2020-11-03T09:48:49.301166-05:00",
        "last_deployed": "2020-11-05T11:24:37.096888-05:00",
        "deleted": "",
        "description": "Upgrade complete",
        "status": "installed",
        "notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
      },
      "chart": {
        "metadata": {
          "name": "cloudflare-dyndns",
          "home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
          "sources": [
            "https://github.com/hotio/docker-cloudflare-ddns/",
            "https://github.com/billimek/billimek-charts"
          ],
          "version": "2.0.0",
          "description": "Dynamic DNS using Cloudflare's DNS Services",
          "keywords": [
            "cloudflare",
            "dynamicdns"
          ],
          "maintainers": [
            {
              "name": "billimek",
              "email": "jeff@billimek.com"
            }
          ],
          "icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
          "apiVersion": "v1",
          "appVersion": "1.0",
          "deprecated": false
        },
        "values": {
          "affinity": {},
          "cloudflare": {
            "detection_mode": "dig-google.com",
            "hosts": "somehosts",
            "log_level": 1.0,
            "record_types": "somerecordtypes",
            "sleep_interval": 300.0,
            "token": "sometoken",
            "user": "someuser",
            "zones": "somezones"
          },
          "image": {
            "pullPolicy": "Always",
            "repository": "hotio/cloudflare-ddns",
            "tag": "latest"
          },
          "nodeSelector": {},
          "replicaCount": 1.0,
          "resources": {},
          "tolerations": []
        }
      },
      "config": {
        "affinity": {},
        "cloudflare": {
          "detection_mode": "dig-google.com",
          "hosts": "somehosts",
          "log_level": 1.0,
          "record_types": "somerecordtypes",
          "sleep_interval": 300.0,
          "token": "sometoken",
          "user": "someuser",
          "zones": "somezones"
        },
        "image": {
          "pullPolicy": "Always",
          "repository": "hotio/cloudflare-ddns",
          "tag": "latest"
        },
        "nodeSelector": {},
        "replicaCount": 1.0,
        "resources": {},
        "tolerations": []
      },
      "version": 10,
      "namespace": "my-namespace",
      "keepHistory": false,
      "chartVersion": "cloudflare-dyndns / 2.0.0"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/releases?cluster_id=:cluster_id

Or

GET /services/:service_code/:environment_name/releases?namespace=default&cluster_id=:cluster_id

Retrieve a list of all releases in a given environment.

Required
cluster_id string	The id of the cluster in which to list the releases.

Optional
namespace string	The namespace to list the release. This needs the exact value.

Attributes
id string	The release id, of the form namespace/releaseName.
name string	The name of the release.
info object	The information about the release.
info.first_deployed string	The annotations of the pod.
info.last_deployed string	The date of creation of the pod as a string.
info.deleted string	The labels associated to the pod.
info.description string	The name of the pod.
info.status string	The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback.
info.notes string	The notes linked to the release.
chart object	The information related to the chart of used in the release.
chart.version string	The version of the chart.
chart.metadata object	The metadata associated to the chart.
chart.metadata.name string	The name of the chart.
chart.metadata.home string	The home URL for the chart.
chart.metadata.sources list	The list of source of the charts.
chart.metadata.version string	The version of the chart.
chart.metadata.description string	The description of the chart.
chart.metadata.keywords list	The list of keywords linked to the chart.
chart.metadata.maintainers list	The list of the maintainer contact information.
chart.metadata.icon string	The icon URL for the chart.
chart.metadata.appVersion string	The version of the application.
chart.metadata.deprecate bool	If the chart is deprecated or not of the application.
config object	All values that were used to install the release.
version string	The revision of the release.
namespace string	The namespace to which the release is installed.

The information is not totally returned in the list. We filter out the manifest portion. We also filter out the files and the templates of the chart details. This information will be present in the GET request for an individual release.

Get release

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/my-namespace/my-cloudflare?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "my-namespace/my-cloudflare",
    "name": "my-cloudflare",
    "info": {
      "first_deployed": "2020-11-03T09:48:49.301166-05:00",
      "last_deployed": "2020-11-05T19:44:46.775668959Z",
      "deleted": "",
      "description": "Upgrade complete",
      "status": "installed",
      "notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
    },
    "chart": {
      "metadata": {
        "name": "cloudflare-dyndns",
        "home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
        "sources": [
          "https://github.com/hotio/docker-cloudflare-ddns/",
          "https://github.com/billimek/billimek-charts"
        ],
        "version": "2.0.0",
        "description": "Dynamic DNS using Cloudflare's DNS Services",
        "keywords": [
          "cloudflare",
          "dynamicdns"
        ],
        "maintainers": [
          {
            "name": "billimek",
            "email": "jeff@billimek.com"
          }
        ],
        "icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
        "apiVersion": "v1",
        "appVersion": "1.0",
        "deprecated": false
      },
      "templates": [
        {
          "name": "templates/NOTES.txt",
          "data": "WW91I...fScp"
        },
        {
          "name": "templates/_helpers.tpl",
          "data": "e3svKi...9Cg=="
        },
        {
          "name": "templates/deployment.yaml",
          "data": "YXBpVm...9Cg=="
        },
        {
          "name": "templates/secret.yaml",
          "data": "YXBpVmVy...X0="
        }
      ],
      "values": {
        "affinity": {},
        "cloudflare": {
          "detection_mode": "dig-google.com",
          "hosts": "somehosts",
          "log_level": 1.0,
          "record_types": "somerecordtypes",
          "sleep_interval": 300.0,
          "token": "sometoken",
          "user": "someuser",
          "zones": "somezones"
        },
        "image": {
          "pullPolicy": "Always",
          "repository": "hotio/cloudflare-ddns",
          "tag": "latest"
        },
        "nodeSelector": {},
        "replicaCount": 1.0,
        "resources": {},
        "tolerations": []
      },
      "files": [
        {
          "name": ".helmignore",
          "data": "IyBQYX...b2oK"
        },
        {
          "name": "README.md",
          "data": "IyBE..4K"
        }
      ]
    },
    "manifest": "---\n# Source: cloudflare-dyndns/templates/secret.yaml\napiVersion: v1\n...",
    "config": {
      "affinity": {},
      "cloudflare": {
        "detection_mode": "dig-google.com",
        "hosts": "somehosts",
        "log_level": 1.0,
        "record_types": "somerecordtypes",
        "sleep_interval": 300.0,
        "token": "sometoken",
        "user": "someuser",
        "zones": "somezones"
      },
      "image": {
        "pullPolicy": "Always",
        "repository": "hotio/cloudflare-ddns",
        "tag": "latest"
      },
      "nodeSelector": {},
      "replicaCount": 1.0,
      "resources": {},
      "tolerations": []
    },
    "version": 11,
    "namespace": "my-namespace",
    "keepHistory": false,
    "chartVersion": "cloudflare-dyndns / 2.0.0"
  }
}

GET /services/:service_code/:environment_name/releases?cluster_id=:cluster_id

Retrieve a release in a given environment.

Required
cluster_id string	The id of the cluster in which to list the releases.

Attributes
id string	The release id, of the form namespace/releaseName.
name string	The name of the release.
info object	The information about the release.
info.first_deployed string	The date the release was created.
info.last_deployed string	The date the release was last updated.
info.deleted string	The labels associated to the pod
info.description string	Description of the release's status.
info.status string	The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback.
info.notes string	The notes linked to the release.
chart object	The information related to the chart used to install the release.
chart.version string	The version of the chart.
chart.metadata object	The metadata associated to the chart.
chart.metadata.name string	The name of the chart.
chart.metadata.home string	The home URL for the chart.
chart.metadata.sources list	The list of source of the charts.
chart.metadata.version string	The version of the chart.
chart.metadata.description string	The description of the chart.
chart.metadata.keywords list	The list of keywords linked to the chart.
chart.metadata.maintainers list	The list of the maintainer contact information.
chart.metadata.icon string	The icon URL for the chart.
chart.metadata.appVersion string	The version of the application.
chart.metadata.deprecate bool	If the chart is deprecated or not of the application.
chart.templates list	The list of templates contained inside the chart.
chart.templates.name string	The path name of the template inside the chart.
chart.templates.data string	The contents of the template. This is a base64 encoded string.
chart.files list	The list of files contained inside the chart. These are not YAML files unlike the templates.
chart.files.name string	The path name of the file inside the chart.
chart.files.data string	The contents of the file. This is a base64 encoded string.
manifest string	The YAML Kubernetes resources created by the Helm templating.
config object	All values that were used to install the release.
version string	The revision of the release.
namespace string	The namespace to which the release is installed.

Rollback release to previous revision

curl -X POST </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=rollback&cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": {
      "name": "aerospike-1579797954",
      "version": 8,
      "info": {
          "deleted": "",
          "description": "Rollback to 6",
          "status": "deployed",
          ...
      ...
  },
  "taskId": "13943961-4a2c-4439-b7c9-05113d3b593a",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/releases/:id?operation=rollback&cluster_id=:cluster_id

Rollback a release in a given environment to the previous revision.

Required
cluster_id string	The id of the cluster in which to rollback the release.

Attributes
data Object	The release object. See get release for a description of the release attributes.
taskId string	The task id related to the pod rollback.
taskStatus string	The status of the operation.

Upgrade release

curl -X POST </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/my-namespace/my-aerospike?operation=upgrade&cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
   -d "request_body"

Request body examples:

// Change to the latest version of a chart
{
    "upgradeChart": {
        "name": "aerospike",
        "repository": {
            "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
        }
    }
}


// Change to a specific version of a chart
{
    "upgradeChart": {
        "name": "aerospike",
        "version": "4.9.0",
        "repository": {
            "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
        }
    }
}

// Change the values for the latest version
{
    "upgradeChart": {
        "name": "aerospike",
        "repository": {
            "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
        }
    },
    "upgradeValues": "\"replicaCount\": 3"
}

The above commands return JSON structured like this:

{
  "taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/releases/:id?operation=upgrade&cluster_id=:cluster_id

Upgrade a release in a given environment.

Required
upgradeChart Object	The chart object that should be used to ugprade the release.
upgradeChart.name string	The chart name.
repository Object	The repository object to which the chart belongs.
repository.url string	The repository's URL.

Optional
upgradeChart.version string	The chart version that should be used to upgrade the chart. If none is provided, the latest is used.
upgradeChart.values string	YAML structured text that will overwrite the default values for the upgrade/installation of the chart.

Attributes
taskId string	The task id related to the pod upgrade.
taskStatus string	The status of the operation.

Uninstall a release

curl -X POST </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=uninstall&cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"
   -d "request_body"

Request body example:

{
  "keepHistory": true
}

The above command returns a JSON structured like this:

{
  "data": {
    "version": 0,
    "keepHistory": false
  },
  "taskId": "938f11b2-b37d-459e-8cf2-dea05c4d8f63",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/releases/:id?operation=uninstall&cluster_id=:cluster_id

Uninstall a release in a given environment.

Required
cluster_id string	The id of the cluster in which to uninstall the release.

Optional
keepHistory bool	If true, will keep release history after uninstalling. Defaults to false.

Attributes
version string	The uninstalled release's revision. Revision 0 indicated it was uninstalled.
keepHistory string	The keepHistory value used when uninstalling the chart.
taskId string	The task id related to the pod uninstall.
taskStatus string	The status of the operation.

Charts

List charts

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/charts?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "helm-stable/aerospike",
      "name": "aerospike",
      "description": "A Helm chart for Aerospike in Kubernetes",
      "version": "0.3.3",
      "license": "",
      "deprecated": false,
      "repository": {
        "url": "https://kubernetes-charts.storage.googleapis.com",
        "name": "helm-stable",
        "kind": 0,
        "official": false,
        "displayName": "Stable",
        "repositoryId": "3cc327ae-9403-4521-9b71-f9a41d5f86c8",
        "organizationName": "helm",
        "verifiedPublisher": false,
        "organizationDisplayName": "Helm"
      },
      "packageId": "c4b6ad70-898d-4093-bec8-089d5f48daeb",
      "displayName": "",
      "normalizedName": "aerospike",
      "appVersion": "v4.5.0.5",
      "logoImageId": "50bcf132-ff98-4f9a-9e6a-0c0b06649e48",
      "logoImageUrl": "https://artifacthub.io/image/50bcf132-ff98-4f9a-9e6a-0c0b06649e48"
    }
  ],
  "metadata": {
    "pageSize": 50,
    "pageCurrent": 1,
    "recordCount": 148
  }
}

GET /services/:service_code/:environment_name/charts?cluster_id=:cluster_id

Retrieve a list of all charts in a given environment. To get more chart details, such as available versions, the chart's readme and list of maintainers, see the GET request for an individual chart.

Required
cluster_id string	The id of the cluster in which to list the charts.

Attributes
Attributes
----------------------------------------------------	------------------------------------------------------------------------------------------------------------
id string	The id for the chart, of the form repositoryName/chartName.
name string	The chart name.
description string	The chart description.
version string	The latest chart version.
license string	The chart's license.
deprecated boolean	True if the chart is deprecated.
repository object	The chart's parent repository.
repoository.url string	The repository URL.
repository.name string	The repository name.
repository.kind integer	The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }.
repository.official boolean	True if it is an official repository. That is, if the publisher owns the software deployed by the package.
repository.displayName string	The repository's display name.
repository.repositoryId UUID	The UUID of the repository.
repository.organizationName string	The name of the organization that owns the repository.
repository.organizationDisplayName string	The display name of the organization that owns the repository.
repository.verifiedPublisher boolean	True if the publisher owns the repository.
packageId UUID	The UUID of the package, given by ArtifactHub.
displayName string	The chart's display name.
normalizedName string	The chart's normalized name.
appVersion string	The chart's app version.
logoImageId UUID	The UUID of the package's logo, given by ArtifactHub.
logoImageUrl string	The URL for the chart's logo.

Get chart

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/charts/k8s-at-home/cloudflare-dyndns?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": {
    "keywords": [
      "cloudflare",
      "dynamicdns"
    ],
    "maintainers": [
      {
        "name": "billimek",
        "email": "jeff@billimek.com"
      }
    ],
    "links": [
      {
        "url": "https://github.com/hotio/docker-cloudflare-ddns/",
        "name": "source"
      },
      {
        "url": "https://github.com/billimek/billimek-charts",
        "name": "source"
      }
    ],
    "homeUrl": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
    "availableVersions": [
      {
        "version": "1.0.0",
        "createdAt": 1576998322
      },
      {
        "version": "2.0.0",
        "createdAt": 1578688072
      }
    ],
    "readMe": "# Dynamic DNS using Cloudflare's DNS Services\n...",
    "id": "k8s-at-home/cloudflare-dyndns",
    "name": "cloudflare-dyndns",
    "description": "Dynamic DNS using Cloudflare's DNS Services",
    "version": "2.0.0",
    "license": "",
    "deprecated": false,
    "repository": {
      "url": "https://k8s-at-home.com/charts/",
      "name": "k8s-at-home",
      "kind": 0,
      "official": false,
      "displayName": "charts",
      "repositoryId": "9b40a3b3-ed2a-405f-8919-3b824d4f661d",
      "organizationName": "k8s-at-home",
      "verifiedPublisher": true,
      "organizationDisplayName": "k8s@home"
    },
    "packageId": "a6cd6148-977a-4852-8761-80234f39d90b",
    "displayName": "",
    "normalizedName": "cloudflare-dyndns",
    "appVersion": "1.0",
    "logoImageId": "3a0eac41-21b4-4a1b-b127-c7e70123eda8",
    "logoImageUrl": "https://artifacthub.io/image/3a0eac41-21b4-4a1b-b127-c7e70123eda8"
  }
}

GET /services/:service_code/:environment_name/charts/:id?cluster_id=cluster_id

Retrieve a specific chart in a given environment.

Required
cluster_id string	The id of the cluster in which to get the chart.

Attributes
id string	The id for the chart, of the form repositoryName/chartName.
name string	The chart name.
description string	The chart description.
version string	The latest chart version.
license string	The chart's license.
deprecated boolean	True if the chart is deprecated.
repository object	The chart's parent repository.
repoository.url string	The repository URL.
repository.name string	The repository name.
repository.kind integer	The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }.
repository.official boolean	True if it is an official repository. That is, if the publisher owns the software deployed by the package.
repository.displayName string	The repository's display name.
repository.repositoryId UUID	The UUID of the repository.
repository.organizationName string	The name of the organization that owns the repository.
repository.organizationDisplayName string	The display name of the organization that owns the repository.
repository.verifiedPublisher boolean	True if the publisher owns the repository.
packageId UUID	The UUID of the package, given by ArtifactHub.
displayName string	The chart's display name.
normalizedName string	The chart's normalized name.
appVersion string	The chart's app version.
logoImageId UUID	The UUID of the package's logo, given by ArtifactHub.
logoImageUrl string	The URL for the chart's logo.
keywords Array[string]	The chart's keywords.
maintainers Array[Object]	The names and emails of chart maintainers.
homeUrl Array[Object]	The chart's home URL.
availableVersions Array[Object]	The available chart versions and their created dates.

Install chart

curl --request POST </span>
  --url https://cloudmc_endpoint/api/v1/services/a_service/an_environment/charts?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1 </span>
  --header 'MC-Api-Key: your_api_key' </span>
  --data '{
    "namespace": "my-namespace",
    "releaseName": "my-aerospike",
    "name": "aerospike",
    "version": "5.0.0",
  "values": ""
    "repository": {
        "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
    }
}'

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/charts?cluster_id=:cluster_id

Install a chart in a given environment.

Required Query Parameters
cluster_id string	The id of the cluster in which to install the chart.

Required Attributes
cluster_id string	The id of the cluster in which to install the chart.
namespace string	The namespace in which the chart will be installed.
releaseName string	The desired release name.
name string	The chart name.
repository object	The chart's parent repository from which it should be installed.
repoository.url string	The repository URL.

Optional Attributes
version string	The chart version to be installed. Defaults to the latest version if left blank.
values string	The values used to install the chart. Must be a valid Yaml format. If not provided, the chart's default values will be used.
insecureServer boolean	True if accessing the chart requires an unsecured connection.

Images

Images are virtual machine images that have a virtual disk which contains a bootable operating system.

List images

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/gcp/test-area/images"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "archiveSizeBytes": "10843137280",
      "creationTimestamp": "2019-05-14T16:49:57.269-07:00",
      "description": "Debian, Debian GNU/Linux, 9 (stretch), amd64 built on 20190514",
      "diskSizeGb": "10",
      "family": "debian-9",
      "guestOsFeatures": [
        {
          "type": "VIRTIO_SCSI_MULTIQUEUE"
        }
      ],
      "kind": "compute#image",
      "labelFingerprint": "42WmSpB8rSM=",
      "licenseCodes": [
        "1000205"
      ],
      "licenses": [
        "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/licenses/debian-9-stretch"
      ],
      "rawDisk": {
        "containerType": "TAR",
        "source": ""
      },
      "selfLink": "https://www.googleapis.com/compute/v1/projects/debian-cloud/global/images/debian-9-stretch-v20190514",
      "sourceType": "RAW",
      "status": "READY",
      "vendorFamily": "debian-cloud",
      "shortName": "Debian",
      "iconUrl": "/rest/services/assets/gcp/os_logo/debian.png",
      "id": "2447790134347098827",
      "name": "debian-9-stretch-v20190514"
    },
    {
      "archiveSizeBytes": "16469314560",
      "creationTimestamp": "2019-05-15T19:01:21.060-07:00",
      "description": "CentOS, CentOS, 7, x86_64 built on 20190515",
      "diskSizeGb": "10",
      "family": "centos-7",
      "kind": "compute#image",
      "labelFingerprint": "42WmSpB8rSM=",
      "licenseCodes": [
        "1000207"
      ],
      "licenses": [
        "https://www.googleapis.com/compute/v1/projects/centos-cloud/global/licenses/centos-7"
      ],
      "rawDisk": {
        "containerType": "TAR",
        "source": ""
      },
      "selfLink": "https://www.googleapis.com/compute/v1/projects/centos-cloud/global/images/centos-7-v20190515",
      "sourceType": "RAW",
      "status": "READY",
      "vendorFamily": "centos-cloud",
      "shortName": "CentOS",
      "iconUrl": "/rest/services/assets/gcp/os_logo/centos.png",
      "id": "4658005417542122143",
      "name": "centos-7-v20190515"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/images

Retrieve a list of available images.

Attributes
archiveSizeBytes string	Size of the image tar.gz archive stored in Google Cloud Storage (in bytes).
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
diskSizeGb string	Size of the image when restored onto a persistent disk (in GB).
family string	The name of the image family to which this image belongs.
kind string	Type of the resource.
labelFingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
licenseCodes Array[integer]	License codes indicating which licenses are attached to this image..
licenses Array[URI]	Any applicable license URI.
rawDisk Object	The parameters of the raw disk image.
selfLink string	Server-defined URL for this resource.
sourceType string	The type of the image used to create this disk. The default and only value is RAW.
status string	The status of the image. An image can be used to create other resources, such as instances, only after the image has been successfully created and the status is set to READY. Possible values are FAILED, PENDING, or READY.
vendorFamily string	Image family's vendor name.
shortName string	A short version of the OS image's name.
iconUrl string	Icon representing the OS image.
id UUID	The image's id.
name string	The image's name.

Retrieve an image

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/gcp/test-area/images/4658005417542122143"

The above command returns a JSON structured like this:

{
   "data": {
      "archiveSizeBytes": "16469314560",
      "creationTimestamp": "2019-05-15T19:01:21.060-07:00",
      "description": "CentOS, CentOS, 7, x86_64 built on 20190515",
      "diskSizeGb": "10",
      "family": "centos-7",
      "kind": "compute#image",
      "labelFingerprint": "42WmSpB8rSM=",
      "licenseCodes": [
        "1000207"
      ],
      "licenses": [
        "https://www.googleapis.com/compute/v1/projects/centos-cloud/global/licenses/centos-7"
      ],
      "rawDisk": {
        "containerType": "TAR",
        "source": ""
      },
      "selfLink": "https://www.googleapis.com/compute/v1/projects/centos-cloud/global/images/centos-7-v20190515",
      "sourceType": "RAW",
      "status": "READY",
      "vendorFamily": "centos-cloud",
      "shortName": "CentOS",
      "iconUrl": "/rest/services/assets/gcp/os_logo/centos.png",
      "id": "4658005417542122143",
      "name": "centos-7-v20190515"
    }
}

GET /services/:service_code/:environment_name/images/:id

Retrieve information about an image.

Attributes
archiveSizeBytes string	Size of the image tar.gz archive stored in Google Cloud Storage (in bytes).
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
diskSizeGb string	Size of the image when restored onto a persistent disk (in GB).
family string	The name of the image family to which this image belongs.
kind string	Type of the resource.
labelFingerprint string	A base64-encoded string. A hash of the label's contents and used for optimistic locking.
licenseCodes Array[integer]	License codes indicating which licenses are attached to this image.
licenses Array[URI]	Any applicable license URI.
rawDisk Object	The parameters of the raw disk image.
selfLink string	Server-defined URL for this resource.
sourceType string	The type of the image used to create this disk. The default and only value is RAW.
status string	The status of the image. An image can be used to create other resources, such as instances, only after the image has been successfully created and the status is set to READY. Possible values are FAILED, PENDING, or READY.
vendorFamily string	Image family's vendor name.
shortName string	A short version of the OS image's name.
iconUrl string	Icon representing the OS image.
id UUID	The image's id.
name string	The image's name.

Regions

A region is a geographical area where a resource is located. Regions contains multiple Zones.

List regions

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/gcp/test-area/regions"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "creationTimestamp": "1969-12-31T16:00:00.000-08:00",
      "description": "northamerica-northeast1",
      "id": "1330",
      "kind": "compute#region",
      "name": "northamerica-northeast1",
      "quotas": [
        {
          "limit": 24.0,
          "metric": "CPUS",
          "usage": 0.0
        },
        {
          "limit": 4096.0,
          "metric": "DISKS_TOTAL_GB",
          "usage": 40.0
        }
      ],
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1",
      "status": "UP",
      "zones": [
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-b",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-c"
      ]
    },
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/regions

Retrieve a list of available regions, filtered by the service connection's policies.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
id UUID	The region's id.
kind string	Type of the resource.
name string	The region's name.
quotas Array[object]	Quotas assigned to this region.
selfLink string	Server-defined URL for this resource.
status string	tatus of the region, either UP or DOWN.
zones Array[URL]	A list of zones available in this region, in the form of resource URLs.

Retrieve a region

curl -H "MC-Api-Key: your_api_key" \
    "https://cloudmc_endpoint/api/v1/services/gcp/test-area/regions/1330"

The above command returns a JSON structured like this:

{
   "data": {
      "creationTimestamp": "1969-12-31T16:00:00.000-08:00",
      "description": "northamerica-northeast1",
      "id": "1330",
      "kind": "compute#region",
      "name": "northamerica-northeast1",
      "quotas": [
        {
          "limit": 24.0,
          "metric": "CPUS",
          "usage": 0.0
        },
        {
          "limit": 4096.0,
          "metric": "DISKS_TOTAL_GB",
          "usage": 40.0
        }
      ],
      "selfLink": "https://www.googleapis.com/compute/v1/projects/test-area-oox/regions/northamerica-northeast1",
      "status": "UP",
      "zones": [
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-a",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-b",
        "https://www.googleapis.com/compute/v1/projects/test-area-oox/zones/northamerica-northeast1-c"
      ]
    }
}

GET /services/:service_code/:environment_name/regions/:id

Retrieve information about a region.

Attributes
creationTimestamp string	Creation timestamp in RFC3339 text format.
description string	An optional description of this resource.
id UUID	The region's id.
kind string	Type of the resource.
name string	The region's name.
quotas Array[object]	Quotas assigned to this region.
selfLink string	Server-defined URL for this resource.
status string	tatus of the region, either UP or DOWN.
zones Array[URL]	A list of zones available in this region, in the form of resource URLs.

Kubernetes plugin

The Kubernetes plugin provides endpoints to carrying out operations on CloudMC Kubernetes entities.

Namespaces

List namespaces

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "auth",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 3
  }
}

GET /services/:service_code/:environment_name/namespaces

Retrieve a list of all namespaces in a given environment.

Attributes
id string	The id of the namespace.
metadata object	The metadata of the namespace.
spec object	The specification describes the attributes on a namespace.
status object	The status information of the namespace.

Get a namespace

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces/cert-manager"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cert-manager",
    "apiVersion": "v1",
    "kind": "Namespace",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/namespaces/:id

Retrieve a namespace and all its info in a given environment.

Attributes
id string	The id of the namespace.
apiVersion string	APIVersion defines the versioned schema of this representation of a namespace object.
metadata object	The metadata of the namespace.
spec object	The specification describes the attributes on a namespace.
status object	The status information of the namespace.

Create a namespace

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Namespace",
  "metadata": {
    "name": "test-namespace"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/namespaces

Create a namespace in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the namespace.
metadata object	The metadata of the namespace.
metadata.name string	The name of the namespace.

Return value:

Attributes
taskId string	The id corresponding to the create namespace task.
taskStatus string	The status of the operation.

Delete a namespace

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces/test-namespace"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/namespaces/:id

Delete a namespace from a given environment.

Attributes
taskId string	The id corresponding to the delete namespaces task.
taskStatus string	The status of the operation.

Workloads

Pods

List pods

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-aerospike-0/default",
      "metadata": {
        "annotations": {
          "checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
        },
        "creationTimestamp": "2020-01-20T09:35:02.000-05:00",
        "generateName": "my-aerospike-",
        "labels": {
          "app": "aerospike",
          "controller-revision-hash": "my-aerospike-d9969496d",
          "release": "my-aerospike",
          "statefulset.kubernetes.io/pod-name": "my-aerospike-0"
        },
        "name": "my-aerospike-0",
        "namespace": "default",
        "ownerReferences": [
          {
            "apiVersion": "apps/v1",
            "blockOwnerDeletion": true,
            "controller": true,
            "kind": "StatefulSet",
            "name": "my-aerospike",
            "uid": "0b00ea3d-3b92-11ea-935e-025000000001"
          }
        ],
        "resourceVersion": "95058",
        "selfLink": "/api/v1/namespaces/default/pods/my-aerospike-0",
        "uid": "0b055519-3b92-11ea-935e-025000000001"
      },
      "spec": {
        "containers": [
          {
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imagePullPolicy": "IfNotPresent",
            "name": "my-aerospike",
            "ports": [
              {
                "containerPort": 3000,
                "name": "clients",
                "protocol": "TCP"
              },
              {
                "containerPort": 3002,
                "name": "mesh",
                "protocol": "TCP"
              },
              {
                "containerPort": 3003,
                "name": "info",
                "protocol": "TCP"
              }
            ],
            "readinessProbe": {
              "failureThreshold": 3,
              "initialDelaySeconds": 15,
              "periodSeconds": 10,
              "successThreshold": 1,
              "tcpSocket": {
                "port": 3000
              },
              "timeoutSeconds": 1
            },
            "resources": {},
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "volumeMounts": [
              {
                "mountPath": "/etc/aerospike",
                "name": "config-volume"
              },
              {
                "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
                "name": "default-token-64jnc",
                "readOnly": true
              }
            ]
          }
        ],
        "dnsPolicy": "ClusterFirst",
        "enableServiceLinks": true,
        "hostname": "my-aerospike-0",
        "nodeName": "docker-desktop",
        "priority": 0,
        "restartPolicy": "Always",
        "schedulerName": "default-scheduler",
        "securityContext": {},
        "serviceAccount": "default",
        "serviceAccountName": "default",
        "subdomain": "my-aerospike",
        "terminationGracePeriodSeconds": 30,
        "tolerations": [
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/not-ready",
            "operator": "Exists",
            "tolerationSeconds": 300
          },
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/unreachable",
            "operator": "Exists",
            "tolerationSeconds": 300
          }
        ],
        "volumes": [
          {
            "configMap": {
              "defaultMode": 420,
              "items": [
                {
                  "key": "aerospike.conf",
                  "path": "aerospike.conf"
                }
              ],
              "name": "my-aerospike"
            },
            "name": "config-volume"
          },
          {
            "name": "default-token-64jnc",
            "secret": {
              "defaultMode": 420,
              "secretName": "default-token-64jnc"
            }
          }
        ]
      },
      "status": {
        "conditions": [
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "Initialized"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "Ready"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "ContainersReady"
          },
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "PodScheduled"
          }
        ],
        "containerStatuses": [
          {
            "containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
            "lastState": {
              "terminated": {
                "containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
                "exitCode": 255,
                "finishedAt": "2020-01-21T15:04:35.000-05:00",
                "reason": "Error",
                "startedAt": "2020-01-20T10:28:19.000-05:00"
              }
            },
            "name": "my-aerospike",
            "ready": true,
            "restartCount": 2,
            "state": {
              "running": {
                "startedAt": "2020-01-21T15:05:16.000-05:00"
              }
            }
          }
        ],
        "hostIP": "192.168.65.3",
        "phase": "Running",
        "podIP": "10.1.0.129",
        "qosClass": "BestEffort",
        "startTime": "2020-01-20T09:35:02.000-05:00"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/pods

Retrieve a list of all pods in a given environment.

Attributes
id string	The id of the pod.
metadata object	The metadata of the pod.
metadata.annotations map	The annotations of the pod.
metadata.creationTimestamp string	The date of creation of the pod as a string.
metadata.labels map	The labels associated to the pod.
metadata.name string	The name of the pod.
metadata.namespace string	The namespace in which the pod is created.
metadata.uid object	The UUID of the pod.
spec object	The specification used to create and run the pod.
spec.container string	The name of the container running.
status object	The status information of the pod.
status.phase string	The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a pod

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/my-aerospike-0/default"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-aerospike-0/default",
      "metadata": {
        "annotations": {
          "checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
        },
        "creationTimestamp": "2020-01-20T09:35:02.000-05:00",
        "generateName": "my-aerospike-",
        "labels": {
          "app": "aerospike",
          "controller-revision-hash": "my-aerospike-d9969496d",
          "release": "my-aerospike",
          "statefulset.kubernetes.io/pod-name": "my-aerospike-0"
        },
        "name": "my-aerospike-0",
        "namespace": "default",
        "ownerReferences": [
          {
            "apiVersion": "apps/v1",
            "blockOwnerDeletion": true,
            "controller": true,
            "kind": "StatefulSet",
            "name": "my-aerospike",
            "uid": "0b00ea3d-3b92-11ea-935e-025000000001"
          }
        ],
        "resourceVersion": "95058",
        "selfLink": "/api/v1/namespaces/default/pods/my-aerospike-0",
        "uid": "0b055519-3b92-11ea-935e-025000000001"
      },
      "spec": {
        "containers": [
          {
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imagePullPolicy": "IfNotPresent",
            "name": "my-aerospike",
            "ports": [
              {
                "containerPort": 3000,
                "name": "clients",
                "protocol": "TCP"
              },
              {
                "containerPort": 3002,
                "name": "mesh",
                "protocol": "TCP"
              },
              {
                "containerPort": 3003,
                "name": "info",
                "protocol": "TCP"
              }
            ],
            "readinessProbe": {
              "failureThreshold": 3,
              "initialDelaySeconds": 15,
              "periodSeconds": 10,
              "successThreshold": 1,
              "tcpSocket": {
                "port": 3000
              },
              "timeoutSeconds": 1
            },
            "resources": {},
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "volumeMounts": [
              {
                "mountPath": "/etc/aerospike",
                "name": "config-volume"
              },
              {
                "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
                "name": "default-token-64jnc",
                "readOnly": true
              }
            ]
          }
        ],
        "dnsPolicy": "ClusterFirst",
        "enableServiceLinks": true,
        "hostname": "my-aerospike-0",
        "nodeName": "docker-desktop",
        "priority": 0,
        "restartPolicy": "Always",
        "schedulerName": "default-scheduler",
        "securityContext": {},
        "serviceAccount": "default",
        "serviceAccountName": "default",
        "subdomain": "my-aerospike",
        "terminationGracePeriodSeconds": 30,
        "tolerations": [
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/not-ready",
            "operator": "Exists",
            "tolerationSeconds": 300
          },
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/unreachable",
            "operator": "Exists",
            "tolerationSeconds": 300
          }
        ],
        "volumes": [
          {
            "configMap": {
              "defaultMode": 420,
              "items": [
                {
                  "key": "aerospike.conf",
                  "path": "aerospike.conf"
                }
              ],
              "name": "my-aerospike"
            },
            "name": "config-volume"
          },
          {
            "name": "default-token-64jnc",
            "secret": {
              "defaultMode": 420,
              "secretName": "default-token-64jnc"
            }
          }
        ]
      },
      "status": {
        "conditions": [
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "Initialized"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "Ready"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "ContainersReady"
          },
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "PodScheduled"
          }
        ],
        "containerStatuses": [
          {
            "containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
            "lastState": {
              "terminated": {
                "containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
                "exitCode": 255,
                "finishedAt": "2020-01-21T15:04:35.000-05:00",
                "reason": "Error",
                "startedAt": "2020-01-20T10:28:19.000-05:00"
              }
            },
            "name": "my-aerospike",
            "ready": true,
            "restartCount": 2,
            "state": {
              "running": {
                "startedAt": "2020-01-21T15:05:16.000-05:00"
              }
            }
          }
        ],
        "hostIP": "192.168.65.3",
        "phase": "Running",
        "podIP": "10.1.0.129",
        "qosClass": "BestEffort",
        "startTime": "2020-01-20T09:35:02.000-05:00"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/pods/:id

Retrieve a pod and all its info in a given environment.

Attributes
id string	The id of the pod.
metadata object	The metadata of the pod.
metadata.annotations map	The annotations of the pod.
metadata.creationTimestamp string	The date of creation of the pod as a string.
metadata.labels map	The labels associated to the pod.
metadata.name string	The name of the pod.
metadata.namespace string	The namespace in which the pod is created.
metadata.uid object	The UUID of the pod.
spec object	The specification used to create and run the pod.
spec.container string	The name of the container running.
status object	The status information of the pod.
status.phase string	The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a pod

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods"
  Content-Type: application/json
  {
      "apiVersion": "v1",
    "kind": "Pod",
      "metadata": {
        "name": "edgar-allen-pod",
          "namespace": "default"
    },
      "spec": {
        "containers": [
            {
                "image": "nginx",
                "name": "nginx"
            }
          ]
      }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/pods

Create a pod in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the pod.
metadata object	The metadata of the pod.
metadata.name string	The name of the pod.
spec object	The specification used to create and run the pod.
spec.container.image string	The docker image name.
spec.container.name string	The (unique) name of the container specified as a DNS_LABEL.

Optional Attributes
metadata.namespace string	The namespace in which the pod is created

Return value:

Attributes
taskId string	The id corresponding to the create pod task.
taskStatus string	The status of the operation.

Replace a pod

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/edgar-allen-pod/default"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "kind": "Pod",
      "metadata": {
        "name": "edgar-allen-pod",
          "namespace": "default"
  },
      "spec": {
        "containers": [
            {
                "image": "nginx",
                "name": "nginx"
            }
          ]
      }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/pods/:id

Replace a pod in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the pod.
metadata object	The metadata of the pod.
metadata.name string	The name of the pod.
spec object	The specification used to replace and run the pod.
spec.container.image string	The docker image name.
spec.container.name string	The (unique) name of the container specified as a DNS_LABEL.

Optional Attributes
metadata.namespace string	The namespace in which the pod is replaced.

Return value:

Attributes
taskId string	The id corresponding to the replace pod task.
taskStatus string	The status of the operation.

Delete a pod

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/my-aerospike-0/default"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/pods/:id

Delete a pod from a given environment.

Attributes
taskId string	The id corresponding to the delete pod task.
taskStatus string	The status of the operation.

Deployments

List deployments

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "apm-server-1585600296-apm-server/monitoring",
      "deploymentStatus": "Available",
      "readyRatio": "1/1",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 9
  }
}

GET /services/:service_code/:environment_name/deployments

Retrieve a list of all deployments in a given environment.

Attributes
id string	The id of the deployment.
metadata object	The metadata of the deployment.
metadata.name string	The name of the deployment.
metadata.namespace string	The namespace in which the deployment is created.
metadata.uid object	The UUID of the deployment.
images object	The container images within a deployment.
spec object	The specification used to create and run the deployment.
status object	The status information of the deployment.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a deployment

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/test-aerospike/auth"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "apm-server-1585600296-apm-server/monitoring",
    "deploymentStatus": "Available",
    "readyRatio": "1/1",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/deployments/:id

Retrieve a deployment and all its info in a given environment.

Attributes
id string	The id of the deployment.
deplomentStatus object	The status information of the deployment.
readyRatio object	The ready replicas to total replicas ratio of this deployment set.
metadata object	The metadata of the deployment.
spec object	The specification used to create and run the deployment.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a deployment

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "api-test-deployment-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "nginx"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/deployments

Create a deployment in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the deployment.
metadata object	The metadata of the deployment.
metadata.name string	The name of the deployment.
spec object	The specification used to replace and run the deployment.
spec.selector object	The label query over the deployment's set of resources.
spec.template object	The data a deployment's pod should have when replaced.
spec.spec object	The specification used to replace and run the pod(s) within the deployment.

Optional Attributes
metadata.namespace string	The namespace in which the deployment is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a deployment.

Return value:

Attributes
taskId string	The id corresponding to the replace deployment task.
taskStatus string	The status of the operation.

Replace a deployment

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/deployment-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "deployment-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "nginx"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/deployments/:id

Replace a deployment in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the deployment.
metadata object	The metadata of the deployment.
metadata.name string	The name of the deployment.
spec object	The specification used to create and run the deployment.
spec.selector object	The label query over the deployment's set of resources.
spec.template object	The data a deployment's pod should have when created.
spec.spec object	The specification used to create and run the pod(s) within the deployment.

Optional Attributes
metadata.namespace string	The namespace in which the deployment is created.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a deployment.

Return value:

Attributes
taskId string	The id corresponding to the create deployment task.
taskStatus string	The status of the operation.

Delete a deployment

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/dex/auth"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/deployments/:id

Delete a deployment from a given environment.

Attributes
taskId string	The id corresponding to the delete deployment task.
taskStatus string	The status of the operation.

Daemon Sets

List daemon sets

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "canal/kube-system",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 9
  }
}

GET /services/:service_code/:environment_name/daemonsets

Retrieve a list of all daemon sets in a given environment.

Attributes
id string	The id of the daemon set.
metadata object	The metadata of the daemon set.
spec object	The specification used to create and run the daemon set.
status object	The status information of the daemon set.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a daemon set

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/test-aerospike/auth"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "canal/kube-system",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/daemonsets/:id

Retrieve a daemon set and all its info in a given environment.

Attributes
id string	The id of the daemon set.
metadata object	The metadata of the daemon set.
spec object	The specification used to create and run the daemon set.
status object	The status information of the daemon set.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a daemon set

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "DaemonSet",
  "metadata": {
    "name": "daemonset-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "name": "fluentd-elasticsearch"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "fluentd-elasticsearch"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "fluentd-elasticsearch",
            "image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/daemonsets

Create a daemon set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the daemon set.
metadata object	The metadata of the daemon set.
metadata.name string	The name of the daemon set.
spec object	The specification used to create and run the daemon set.
spec.selector object	The label query over the daemon set's resources.
spec.template object	The data a daemon set's pod should have when created.
spec.spec object	The specification used to create and run the pod(s) within the daemon set.

Optional Attributes
metadata.namespace string	The namespace in which the daemon set is created.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a daemon set.

Return value:

Attributes
taskId string	The id corresponding to the create daemon set task.
taskStatus string	The status of the operation.

Replace a daemon set

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/daemonset-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "DaemonSet",
  "metadata": {
    "name": "daemonset-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "name": "fluentd-elasticsearch"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "fluentd-elasticsearch"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "fluentd-elasticsearch",
            "image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/daemonsets/:id

Replace a daemon set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the daemon set.
metadata object	The metadata of the daemon set.
metadata.name string	The name of the daemon set.
spec object	The specification used to replace and run the daemon set.
spec.selector object	The label query over the daemon set's resources.
spec.template object	The data a daemon set's pod should have when replaced.
spec.spec object	The specification used to create and run the pod(s) within the daemon set.

Optional Attributes
metadata.namespace string	The namespace in which the daemon set is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a daemon set.

Return value:

Attributes
taskId string	The id corresponding to the replace daemon set task.
taskStatus string	The status of the operation.

Delete a daemon set

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/nginx-ingress-controller/ingress-nginx"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/daemonsets/:id

Delete a daemon set from a given environment.

Attributes
taskId string	The id corresponding to the delete daemon set task.
taskStatus string	The status of the operation.

Stateful Sets

List stateful sets

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "test-aerospike/auth",
      "images": ["aerospike/aerospike-server:4.5.0.5"],
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/statefulsets

Retrieve a list of all stateful sets in a given environment.

Attributes
id string	The id of the stateful set.
metadata object	The metadata of the stateful set.
spec object	The specification used to create and run the stateful set.
status object	The status information of the stateful set.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a stateful set

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/test-aerospike/auth"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "test-aerospike/auth",
    "replicaRatio": "1 / 1",
    "images": ["aerospike/aerospike-server:4.5.0.5"],
    "apiVersion": "apps/v1",
    "kind": "StatefulSet",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/statefulsets/:id

Retrieve a stateful set and all its info in a given environment.

Attributes
id string	The id of the stateful set.
metadata object	The metadata of the stateful set.
spec object	The specification used to create and run the stateful set.
status object	The status information of the stateful set.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a stateful set

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "StatefulSet",
  "metadata": {
    "name": "stateful-set-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "k8s.gcr.io/nginx-slim:0.8"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/statefulsets

Create a stateful set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the stateful set.
metadata object	The metadata of the stateful set.
metadata.name string	The name of the stateful set.
spec object	The specification used to create and run the stateful set.
spec.selector object	The label query over the stateful set's of resources.
spec.template object	The data a stateful set's pod should have when created.
spec.spec object	The specification used to create and run the pod(s) within the stateful set.

Optional Attributes
metadata.namespace string	The namespace in which the stateful set is created.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a stateful set.

Return value:

Attributes
taskId string	The id corresponding to the create stateful set task.
taskStatus string	The status of the operation.

Replace a stateful set

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/stateful-set-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "StatefulSet",
  "metadata": {
    "name": "stateful-set-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "k8s.gcr.io/nginx-slim:0.8"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/statefulsets/:id

Replace a stateful set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the stateful set.
metadata object	The metadata of the stateful set.
metadata.name string	The name of the stateful set.
spec object	The specification used to replaced and run the stateful set.
spec.selector object	The label query over the stateful set's of resources.
spec.template object	The data a stateful set's pod should have when replaced.
spec.spec object	The specification used to replace and run the pod(s) within the stateful set.

Optional Attributes
metadata.namespace string	The namespace in which the stateful set is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a stateful set.

Return value:

Attributes
taskId string	The id corresponding to the replace stateful set task.
taskStatus string	The status of the operation.

Delete a stateful set

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/my-aerospike/default"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/statefulsets/:id

Delete a stateful set from a given environment.

Attributes
taskId string	The id corresponding to the delete stateful set task.
taskStatus string	The status of the operation.

Networking

Services

List services

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "alaintest-aerospike/default",
      "ports": ["3000/TCP", "3002/TCP"],
      "type": "ClusterIP",
      "metadata": {},
      "spec": {},
      "status": {
        "loadBalancer": {}
      }
    },
    {
      "id": "alertmanager-operated/monitoring",
      "ports": ["9093/TCP", "9094/TCP", "9094/UDP"],
      "type": "NodePort",
      "apiVersion": "v1",
      "kind": "Service",
      "metadata": {},
      "spec": {},
      "status": {
        "loadBalancer": {}
      }
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/services

Retrieve a list of all services in a given environment.

Attributes
id string	The id of the service
metadata object	The metadata of the service
metadata.name string	The name of the service
metadata.namespace string	The namespace in which the service is created
metadata.uid object	The UUID of the service
type object	The container images within a service
ports object	The list of ports that are exposed by this service
spec object	The attributes that a user creates on a service
spec.selector object	The keys and values corresponding to pod labels, used to determine where service traffic will be routed

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a service

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/test-aerospike/auth"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "test-aerospike/auth",
    "ports": ["3000/TCP", "3002/TCP"],
    "type": "ClusterIP",
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {},
    "spec": {},
    "status": {
      "loadBalancer": {}
    }
  }
}

GET /services/:service_code/:environment_name/services/:id

Retrieve a service and all its info in a given environment.

Attributes
id string	The id of the service
metadata object	The metadata of the service
metadata.name string	The name of the service
metadata.namespace string	The namespace in which the service is created
metadata.uid object	The UUID of the service
type object	The container images within a service
ports object	The list of ports that are exposed by this service
spec object	The attributes that a user creates on a service
spec.selector object	The keys and values corresponding to pod labels, used to determine where service traffic will be routed

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a service

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Service",
  "metadata": {
    "name": "service-name",
    "namespace": "default"
  },
  "spec": {
    "ports": [
      {
        "port": 3000,
        "protocol": "TCP"
      }
    ],
    "type": "ClusterIP"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/services

Create a service in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the service.
metadata object	The metadata of the service.
metadata.name string	The name of the service.
spec object	The specification used to create and run the service.
spec.ports object	The list of ports that are exposed by this service.
spec.type object	The type of service (ClusterIP, NodePort, ExternalName or LoadBalancer)

Optional Attributes
metadata.namespace string	The namespace in which the service is created.
spec.selector object	The label query over the service's set of resources.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a service.

Return value:

Attributes
taskId string	The id corresponding to the create service task.
taskStatus string	The status of the operation.

Replace a service

curl -X PUT \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/service-name/default"

Request body example:

{
    "type": "LoadBalancer",
    "ports": [
        "4000/TCP"
    ],
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {
        "creationTimestamp": "2020-08-13T11:05:00.000-04:00",
        "name": "service-name",
        "namespace": "default",
        "resourceVersion": "170742452",
        "selfLink": "/api/v1/namespaces/default/services/service-name",
        "uid": "a84c8fea-f9d9-47ab-8e58-37059e9f18bd"
    },
    "spec": {
        "clusterIP": "10.245.44.45",
        "externalTrafficPolicy": "Cluster",
        "ports": [
            {
                "nodePort": 31167,
                "port": 3000,
                "protocol": "TCP",
                "targetPort": 306
            }
        ],
        "sessionAffinity": "ClientIP",
        "sessionAffinityConfig": {
            "clientIP": {
                "timeoutSeconds": 10555
            }
        },
        "type": "LoadBalancer"
    },
    "status": {
        "loadBalancer": {}
    }
}

PUT /services/:service_code/:environment_name/services/:id

Replace a service in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the service.
metadata object	The metadata of the service.
metadata.name string	The name of the service.
spec object	The specification used to create and run the service.

Return value:

Attributes
taskId string	The id corresponding to the replace service task.
taskStatus string	The status of the operation.

Delete a service

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/test-service/default"

DELETE /services/:service_code/:environment_name/services/:id

Delete a service from a given environment.

Attributes
taskId string	The id corresponding to the delete service task.
taskStatus string	The status of the operation.

Ingresses

List ingresses

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "cloudmc/cmc-stg",
      "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
      "service": {
        "port": "8080",
        "name": "cloudmc"
      },
      "metadata": {
        "annotations": {},
        "creationTimestamp": "2019-07-11T10:00:18.000-04:00",
        "generation": 10,
        "name": "cloudmc",
        "namespace": "cmc-stg",
        "resourceVersion": "143213903",
        "selfLink": "/apis/extensions/v1beta1/namespaces/cmc-stg/ingresses/cloudmc",
        "uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
      },
      "spec": {
        "rules": [],
        "tls": []
      },
      "status": {
        "loadBalancer": {}
      }
    },
    {
      "id": "cm-acme-http-solver-75png/auth",
      "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
      "service": {
        "port": "8089",
        "name": "cm-acme-http-solver-2x5gv"
      },
      "metadata": {
        "annotations": {},
        "creationTimestamp": "2020-06-24T11:00:49.000-04:00",
        "generateName": "cm-acme-http-solver-",
        "generation": 1,
        "labels": {
          "acme.cert-manager.io/http-domain": "1965164889",
          "acme.cert-manager.io/http-token": "820448657",
          "acme.cert-manager.io/http01-solver": "true"
        },
        "name": "cm-acme-http-solver-75png",
        "namespace": "auth",
        "ownerReferences": [],
        "resourceVersion": "143213968",
        "selfLink": "/apis/extensions/v1beta1/namespaces/auth/ingresses/cm-acme-http-solver-75png",
        "uid": "48720f48-f2bc-45fc-95c5-60cae8ffe11e"
      },
      "spec": {
        "rules": []
      },
      "status": {
        "loadBalancer": {}
      }
    }
  ]
}

GET /services/:service_code/:environment_name/ingresses

Retrieve a list of all ingresses in a given environment.

Attributes
id string	The id of the ingress.
endpoint string	The endpoint of the ingress.
service object	The service associated with the ingress.
service.port string	The port of the service associated with the ingress.
service.name string	The name of the service associated with the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
metadata.namespace string	The namespace in which the ingress is created.
metadata.labels object	The labels associated with the ingress.
metadata.uid object	The UUID of the ingress.
spec object	The attributes that a user specifies for an ingress.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get an ingress

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/cloudmc/cmc-stg"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cloudmc/cmc-stg",
    "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
    "service": {
      "port": "8080",
      "name": "cloudmc"
    },
    "metadata": {
      "annotations": {},
      "creationTimestamp": "2019-07-11T10:00:18.000-04:00",
      "generation": 10,
      "name": "cloudmc",
      "namespace": "cmc-stg",
      "resourceVersion": "143213903",
      "selfLink": "/apis/extensions/v1beta1/namespaces/cmc-stg/ingresses/cloudmc",
      "uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
    },
    "spec": {
      "rules": [],
      "tls": []
    },
    "status": {
      "loadBalancer": {}
    }
  }
}

GET /services/:service_code/:environment_name/ingresses/:id

Retrieve an ingress and all its info in a given environment.

Attributes
id string	The id of the ingress.
endpoint string	The endpoint of the ingress.
service object	The service associated with the ingress.
service.port string	The port of the service associated with the ingress.
service.name string	The name of the service associated with the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
metadata.namespace string	The namespace in which the ingress is created.
metadata.labels object	The labels associated with the ingress.
metadata.uid object	The UUID of the ingress.
spec object	The attributes that a user specifies for an ingress.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create an ingress

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses"
  Content-Type: application/json
  {
  "apiVersion": "networking.k8s.io/v1beta1",
  "kind": "Ingress",
  "metadata": {
    "name": "ingress-name",
    "namespace": "default",
    "annotations": {
      "nginx.ingress.kubernetes.io/rewrite-target": "/"
    }
  },
  "spec": {
    "rules": [
      {
        "hostname": "endpoint.com",
        "http": {
          "paths": [
            {
              "path": "/testpath",
              "pathType": "Prefix",
              "backend": {
                "serviceName": "test",
                "servicePort": 80
              }
            }
          ]
        }
      }
    ]
  }
}

POST /services/:service_code/:environment_name/ingresses

Create an ingress in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
spec object	The specification used to create and run the ingress.
spec.rules object	The list of host rules used to configure the ingress.

Optional Attributes
metadata.namespace string	The namespace in which the ingress is created.

Return value:

Attributes
taskId string	The id corresponding to the create ingress task.
taskStatus string	The status of the operation.

Replace an ingress

curl -X PUT \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/ingress-name/default"

Request body example:

{
  "endpoint": "http://my-endpoint.com",
  "service": {
    "port": "6556",
    "name": "test"
  },
  "apiVersion": "extensions/v1beta1",
  "kind": "Ingress",
  "metadata": {
    "creationTimestamp": "2020-08-13T14:13:42.000-04:00",
    "generation": 3,
    "name": "ingress-name",
    "namespace": "default",
    "resourceVersion": "170302224",
    "selfLink": "/apis/extensions/v1beta1/namespaces/default/ingresses/ingress-name",
    "uid": "c67e6a6a-2b07-4976-8b3d-2ec9fd91ae5d"
  },
  "spec": {
    "rules": [
      {
        "host": "my-endpoint.com",
        "http": {
          "paths": [
            {
              "backend": {
                "serviceName": "test",
                "servicePort": 6556
              },
              "path": "/testpath"
            }
          ]
        }
      }
    ]
  },
  "status": {
    "loadBalancer": {
      "ingress": [
        {
          "hostname": "hostname-worker-01"
        },
        {
          "hostname": "hostname-worker-02"
        },
        {
          "hostname": "hostname-worker-03"
        },
        {
          "hostname": "hostname-worker-04"
        }
      ]
    }
  }
}

PUT /services/:service_code/:environment_name/ingresses/:id

Replace an ingress in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
spec object	The specification used to create and run the ingress.

Return value:

Attributes
taskId string	The id corresponding to the replace ingress task.
taskStatus string	The status of the operation.

Delete an ingress

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/test-ingress/default"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/ingresses/:id

Delete an ingress from a given environment.

Attributes
taskId string	The id corresponding to the delete ingress task.
taskStatus string	The status of the operation.

Configuration

Config Maps

List config maps

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "coredns/kube-system",
      "data": {
        "Corefile": ".:53 {\n    errors\n    health\n    kubernetes cluster.local in-addr.arpa ip6.arpa {\n      pods insecure\n      upstream\n      fallthrough in-addr.arpa ip6.arpa\n    }\n    prometheus :9153\n    forward . /etc/resolv.conf\n    cache 30\n    loop\n    reload\n    loadbalance\n    import custom/*.override\n}\nimport custom/*.server\n"
      },
      "metadata": {}
    }
  ],
  "metadata": {
    "recordCount": 4
  }
}

GET /services/:service_code/:environment_name/configmaps

Retrieve a list of all config maps in a given environment.

Attributes
id string	The id of the config map.
apiVersion string	The API version used to retrieve this config map.
metadata object	The metadata of the config map.

Get a config map

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cert-manager-cainjector-leader-election/kube-system",
    "apiVersion": "v1",
    "kind": "ConfigMap",
    "metadata": {}
  }
}

GET /services/:service_code/:environment_name/configmaps/:id

Retrieve a config map and all its info in a given environment.

Attributes
id string	The id of the config map.
apiVersion string	The API version used to retrieve this config map.
metadata object	The metadata of the config map.

Create a config map

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "game-demo"
  },
  "data": {
    "player_initial_lives": "3",
    "ui_properties_file_name": "user-interface.properties",
    "game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
    "user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/configmaps

Create a config map in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the config map.
metadata object	The metadata of the config map.
metadata.name string	The name of the config map.
data object	The non-confidential data (in key-value pairs) stored in the config map.

Optional Attributes
metadata.namespace string	The namespace in which the config map is created

Return value:

Attributes
taskId string	The id corresponding to the create config maps task.
taskStatus string	The status of the operation.

Replace a config map

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/game-demo/default"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "game-demo",
    "namespace": "default"
  },
  "data": {
    "player_initial_lives": "5",
    "ui_properties_file_name": "user-interface.properties",
    "game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
    "user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/configmaps/:id

Replace a config map in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the config map.
metadata object	The metadata of the config map.
metadata.name string	The name of the config map.
data object	The non-confidential data (in key-value pairs) stored in the config map.

Optional Attributes
metadata.namespace string	The namespace in which the config map is replaced.

Return value:

Attributes
taskId string	The id corresponding to the replace config maps task.
taskStatus string	The status of the operation.

Delete a config map

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/configmaps/:id

Delete a config map from a given environment.

Attributes
taskId string	The id corresponding to the delete config map task.
taskStatus string	The status of the operation.

Secrets

List secrets

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "default-token-xxxmt/default",
      "apiVersion": "v1",
      "encodedData": {
        "ca.crt": "LS0tLS...",
        "namespace": "a3ViZS1zeXN0ZW0=",
        "token": "ZXlKa..."
      },
      "kind": "Secret",
      "metadata": {},
      "type": "kubernetes.io/service-account-token"
    }
  ],
  "metadata": {
    "recordCount": 100
  }
}

GET /services/:service_code/:environment_name/secrets

Retrieve a list of all secrets in a given environment.

Attributes
id string	The id of the secret.
apiVersion string	The API version used to retrieve the secret.
encodedData object	The base64 encoded data stored in the secret.
metadata object	The metadata of the secret.
type string	A string used to facilitate programmatic handling of a secret's data.

Get a secret

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/default-token-xxxmt/default"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "default-token-xxxmt/default",
    "apiVersion": "v1",
    "encodedData": {
      "ca.crt": "LS0tLS...",
      "namespace": "a3ViZS1zeXN0ZW0=",
      "token": "ZXlKa..."
    },
    "kind": "Secret",
    "metadata": {},
    "type": "kubernetes.io/service-account-token"
  }
}

GET /services/:service_code/:environment_name/secrets/:id

Retrieve a secret and all its info in a given environment.

Attributes
id string	The id of the secret.
apiVersion string	The API version used to retrieve the secret.
encodedData object	The base64 encoded data stored in the secret.
metadata object	The metadata of the secret.
type string	A string used to facilitate programmatic handling of a secret's data.

Create a secret

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "stringData": {
    "username": "my-username",
    "password": "my-password"
  }
}

# OR

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "encodedData": {
    "username": "YWRtaW4=",
    "password": "MWYyZDFlMmU2N2Rm"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/secrets

Create a secret in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the secret.
metadata object	The metadata of the secret.
metadata.name string	The name of the secret.

One of the following two attributes is also required.

Attributes
encodedData object	The base64 encoded data stored in the secret.
stringData object	The non-base64 encoded data to be encoded when the secret is created.

Optional Attributes
metadata.namespace string	The namespace in which the secret is created.

Return value:

Attributes
taskId string	The id corresponding to the create secret task.
taskStatus string	The status of the operation.

Replace a secret

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/my-secret/shhh"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret",
    "namespace": "shhh"
  },
  "type": "Opaque",
  "stringData": {
    "username": "my-username",
    "password": "my-new-password"
  }
}

# OR

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/my-secret/shhh"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "encodedData": {
    "username": "YWRtaW4=",
    "password": "MWYyFDZlMmU2N2Rm"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/secrets/:id

Replace a secret in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the secret.
metadata object	The metadata of the secret.
metadata.name string	The name of the secret.

One of the following two attributes is also required.

Attributes
encodedData object	The base64 encoded data stored in the secret.
stringData object	The non-base64 encoded data to be encoded when the secret is replaced.

Optional Attributes
metadata.namespace string	The namespace in which the secret is replaced.

Return value:

Attributes
taskId string	The id corresponding to the replace secret task.
taskStatus string	The status of the operation.

Delete a secret

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/default-token-xxxmt/default"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/secrets/:id

Delete a secret from a given environment.

Attributes
taskId string	The id corresponding to the delete secret task.
taskStatus string	The status of the operation.

Storage

Storage Classes

List storage classes

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "rook-ceph-block",
      "isDefault": true,
      "allowVolumeExpansion": true,
      "metadata": {
        "annotations": {
          "storageclass.kubernetes.io/is-default-class": "true"
        },
        "creationTimestamp": "2020-04-20T16:08:54.000-04:00",
        "name": "rook-ceph-block",
        "resourceVersion": "107033002",
        "selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
        "uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
      },
      "parameters": {
        "clusterID": "rook-ceph",
        "csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
        "csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
        "csi.storage.k8s.io/fstype": "ext4",
        "csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
        "csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
        "csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
        "csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
        "imageFeatures": "layering",
        "imageFormat": "2",
        "pool": "replicapool"
      },
      "provisioner": "rook-ceph.rbd.csi.ceph.com",
      "reclaimPolicy": "Delete",
      "volumeBindingMode": "Immediate"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/storageclasses

Retrieve a list of all storage classes in a given environment.

Attributes
id string	The id of the storage class. This is the name of the resource.
isDefault boolean	Whether or not the storage class is the default one.
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.
metadata object	The metadata of the storage class.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
provisioner string	The provisioner for the storage class.
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Get a storage class

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "rook-ceph-block",
    "isDefault": true,
    "allowVolumeExpansion": true,
    "metadata": {
      "annotations": {
        "storageclass.kubernetes.io/is-default-class": "true"
      },
      "creationTimestamp": "2020-04-20T16:08:54.000-04:00",
      "name": "rook-ceph-block",
      "resourceVersion": "107033002",
      "selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
      "uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
    },
    "parameters": {
      "clusterID": "rook-ceph",
      "csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
      "csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
      "csi.storage.k8s.io/fstype": "ext4",
      "csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
      "csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
      "csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
      "csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
      "imageFeatures": "layering",
      "imageFormat": "2",
      "pool": "replicapool"
    },
    "provisioner": "rook-ceph.rbd.csi.ceph.com",
    "reclaimPolicy": "Delete",
    "volumeBindingMode": "Immediate"
  }
}

GET /services/:service_code/:environment_name/storageclasses/:id

Retrieve a storage class and all its info in a given environment.

Attributes
id string	The id of the storage class. This is the name of the resource
isDefault boolean	Whether or not the storage class is the default one
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.
metadata object	The metadata of the storage class.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
provisioner string	The provisioner for the storage class
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Create a storage class

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses"
  Content-Type: application/json
  {
  "apiVersion": "storage.k8s.io/v1",
  "kind": "StorageClass",
  "metadata": {
    "name": "local-storage-name"
  },
  "provisioner": "kubernetes.io/no-provisioner",
  "volumeBindingMode": "WaitForFirstConsumer"
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/storageclasses

Create a storage class in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the storage class.
metadata object	The metadata of the storage class.
metadata.name string	The name of the storage class.
provisioner string	The provisioner for the storage class
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Optional Attributes
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.

Return value:

Attributes
taskId string	The id corresponding to the create stateful set task.
taskStatus string	The status of the operation.

Replace a storage class

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block"
  Content-Type: application/json
  {
    "apiVersion": "storage.k8s.io/v1",
    "metadata": {
        "name": "hostpath"
    },
    "provisioner": "docker.io/hostpath"
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/storageclasses/:id

Replace a storage class in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the storage class.
metadata object	The metadata of the storage class.
metadata.name string	The name of the storage class.
provisioner object	The type of provisioner.

Optional Attributes
reclaimPolicy string	Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace storage class task.
taskStatus string	The status of the operation.

Delete a storage class

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/storageclasses/:id

Delete a storage class from a given environment.

Attributes
taskId string	The id corresponding to the delete storage class task.
taskStatus string	The status of the operation.

Persistent volumes

List persistent volumes

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
      "metadata": {
        "annotations": {
          "pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
        },
        "creationTimestamp": "2020-07-03T09:12:17.000-04:00",
        "finalizers": ["kubernetes.io/pv-protection"],
        "name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
        "resourceVersion": "147569183",
        "selfLink": "/api/v1/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
        "uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
      },
      "spec": {
        "accessModes": ["ReadWriteOnce"],
        "capacity": {
          "storage": "8Gi"
        },
        "claimRef": {
          "apiVersion": "v1",
          "kind": "PersistentVolumeClaim",
          "name": "data-cmc-cluster-zookeeper-1",
          "namespace": "cmc-kafka",
          "resourceVersion": "147569124",
          "uid": "05097a93-120d-45d2-aaab-0f273849fccd"
        },
        "csi": {
          "driver": "rook-ceph.rbd.csi.ceph.com",
          "fsType": "ext4",
          "nodeStageSecretRef": {
            "name": "rook-csi-rbd-node",
            "namespace": "rook-ceph"
          },
          "volumeAttributes": {
            "clusterID": "rook-ceph",
            "imageFeatures": "layering",
            "imageFormat": "2",
            "pool": "replicapool",
            "storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
          },
          "volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
        },
        "persistentVolumeReclaimPolicy": "Delete",
        "storageClassName": "rook-ceph-block",
        "volumeMode": "Filesystem"
      },
      "status": {
        "phase": "Bound"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/persistentvolumes

Retrieve a list of all persistent volumes in a given environment.

Attributes
id string	The id of the persistent volume. This is the name of the resource.
metadata object	The metadata of the persistent volume.
spec object	The specification of the persistent volume.
spec.accessModes string	The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.capacity.storage string	Storage capacity of the persistent volume.
spec.persistentVolumeReclaimPolicy string	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Get a persistent volume

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2"

The above command returns a JSON structured like this:

{
  "id": "pvc-05097a93-120d-45d2",
  "metadata": {
    "annotations": {
      "pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
    },
    "creationTimestamp": "2020-07-03T09:12:17.000-04:00",
    "finalizers": ["kubernetes.io/pv-protection"],
    "name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
    "resourceVersion": "147569183",
    "selfLink": "/api/v1/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
    "uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
  },
  "spec": {
    "accessModes": ["ReadWriteOnce"],
    "capacity": {
      "storage": "8Gi"
    },
    "claimRef": {
      "apiVersion": "v1",
      "kind": "PersistentVolumeClaim",
      "name": "data-cmc-cluster-zookeeper-1",
      "namespace": "cmc-kafka",
      "resourceVersion": "147569124",
      "uid": "05097a93-120d-45d2-aaab-0f273849fccd"
    },
    "csi": {
      "driver": "rook-ceph.rbd.csi.ceph.com",
      "fsType": "ext4",
      "nodeStageSecretRef": {
        "name": "rook-csi-rbd-node",
        "namespace": "rook-ceph"
      },
      "volumeAttributes": {
        "clusterID": "rook-ceph",
        "imageFeatures": "layering",
        "imageFormat": "2",
        "pool": "replicapool",
        "storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
      },
      "volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
    },
    "persistentVolumeReclaimPolicy": "Delete",
    "storageClassName": "rook-ceph-block",
    "volumeMode": "Filesystem"
  },
  "status": {
    "phase": "Bound"
  }
}

GET /services/:service_code/:environment_name/persistentvolumes/:id

Retrieve a persistent volume and all its info in a given environment.

Attributes
id string	The id of the persistent volume. This is the name of the resource.
metadata object	The metadata of the persistent volume.
spec object	The specification of the persistent volume.
spec.accessModes string	The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.capacity.storage string	Storage capacity of the persistent volume.
spec.persistentVolumeReclaimPolicy string	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Create a persistent volume

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes"
  Content-Type: application/json
   {
      "apiVersion": "v1",
      "metadata": {
         "name": "small-pvc",
         "namespace": "default"
      },
      "spec": {
         "accessModes": [
            "ReadWriteOnce"
         ],
         "resources": {
            "requests": {
               "storage": "10G"
            }
         }
      }
   }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/persistentvolumes

Create a persistent volume in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the persistent volume.
metadata object	The metadata of the persistent volume.
metadata.name string	The name of the persistent volume.
spec object	The spec for the persistent volume.
spec.accessModes array	A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany.
spec.capacity.storage string	Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.
spec.<VOLUME_TYPE> object	Volume types are identified by name and what volume types are supported differ heavily by Kubernetes deployment. The contents of the object also depend on the volume type. Examples of common volumes types are nfs, hostPath, or local.

Optional Attributes
metadata.namespace string	The namespace in which the pod is created, if not specified will create the persistent volume in default.
spec.storageClassName string	Storage class associated to the volume.
spec.claimRef array	The name of the PersistentVolumeClaim associated to the persistent volume.
spec.mountOptions array	Mount options for when a Persistent Volume is mounted on a node.
spec.nodeAffinity array	Defines constraints that limit what nodes this volume can be accessed from.
spec.persistentVolumeReclaimPolicy array	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.volumeMode array	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Return value:

Attributes
taskId string	The id corresponding to the create persistent volume task.
taskStatus string	The status of the operation.

Replace a persistent volume

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/my-persistent-volume"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "kind": "PersistentVolume",
    "metadata": {
        "annotations": {
            "key": "value"
        },
        "name": "persistentvolumes-name"
    },
    "spec": {
        "accessModes": [
            "ReadWriteMany"
        ],
        "capacity": {
            "storage": "2Gi"
        },
        "claimRef": {
            "apiVersion": "v1",
            "kind": "PersistentVolumeClaim",
            "name": "pv-claim-name",
            "namespace": "default",
            "resourceVersion": "259087",
            "uid": "11957feb-1acc-4c7e-911e-f77d5d7be5ac"
        },
        "hostPath": {
            "path": "/etc/path"
        },
        "persistentVolumeReclaimPolicy": "Retain",
        "storageClassName": "standard",
        "volumeMode": "Filesystem"
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/persistentvolumes/:id

Replace a persistent volume in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the volume.
metadata object	The metadata of the volume.
metadata.name string	The name of the volume.
spec object	The specification used to replace and run the volume.
spec.accessModes string	The desired access modes the volume should have.
spec.capacity.storage string	The size of the claim.
spec.hostPath.path string	The path of the directory on the host.

Optional Attributes
metadata.annotations string	Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.
spec.claimRef string	part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound.
spec.persistentVolumeReclaimPolicy string	What happens to a persistent volume when released from its claim.
spec.storageClassName string	Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass.
spec.volumeMode string	Defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace volume task.
taskStatus string	The status of the operation.

Delete a persistent volume

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/persistentvolumes/:id

Delete a perstent volume from a given environment.

Attributes
taskId string	The id corresponding to the delete persistent volume task.
taskStatus string	The status of the operation.

Persistent Volume Claims

List persistent volume claims

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "cmc-staging-mysql/cmc-stg",
      "metadata": {
        "annotations": {
          "pv.kubernetes.io/bind-completed": "yes",
          "pv.kubernetes.io/bound-by-controller": "yes",
          "volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
        },
        "creationTimestamp": "2020-04-27T12:01:22.000-04:00",
        "finalizers": ["kubernetes.io/pvc-protection"],
        "labels": {
          "app": "cmc-staging-mysql",
          "chart": "mysql-0.4.5",
          "heritage": "Helm",
          "release": "cmc-staging"
        },
        "name": "cmc-staging-mysql",
        "namespace": "cmc-stg",
        "resourceVersion": "111495311",
        "selfLink": "/api/v1/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
        "uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
      },
      "spec": {
        "accessModes": ["ReadWriteOnce"],
        "resources": {
          "requests": {
            "storage": "8Gi"
          }
        },
        "storageClassName": "rook-ceph-block",
        "volumeMode": "Filesystem",
        "volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
      },
      "status": {
        "accessModes": ["ReadWriteOnce"],
        "capacity": {
          "storage": "8Gi"
        },
        "phase": "Bound"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/persistentvolumeclaims

Retrieve a list of all persistent volume claims in a given environment.

Attributes
id string	The id of the persistent volume claim. This is the name and namespace of the resource.
metadata object	The metadata of the persistent volume claim.
spec object	The specification of the persistent volume claim.
spec.accessModes string	The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.resources.requests.storage string	The requested storage capacity of the persistent volume.
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status object	The status of the persistent volume claim.
status.phase string	The claim is in one of the following phases: Pending, Bound, Lost or Terminating.
status.accessModes string	The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
status.capacity.storage string	The allocated storage capacity.

Get a persistent volume claim

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cmc-staging-mysql/cmc-stg",
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
      "annotations": {
        "pv.kubernetes.io/bind-completed": "yes",
        "pv.kubernetes.io/bound-by-controller": "yes",
        "volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
      },
      "creationTimestamp": "2020-04-27T12:01:22.000-04:00",
      "finalizers": ["kubernetes.io/pvc-protection"],
      "labels": {
        "app": "cmc-staging-mysql",
        "chart": "mysql-0.4.5",
        "heritage": "Helm",
        "release": "cmc-staging"
      },
      "name": "cmc-staging-mysql",
      "namespace": "cmc-stg",
      "resourceVersion": "111495311",
      "selfLink": "/api/v1/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
      "uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
    },
    "spec": {
      "accessModes": ["ReadWriteOnce"],
      "resources": {
        "requests": {
          "storage": "8Gi"
        }
      },
      "storageClassName": "rook-ceph-block",
      "volumeMode": "Filesystem",
      "volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
    },
    "status": {
      "accessModes": ["ReadWriteOnce"],
      "capacity": {
        "storage": "8Gi"
      },
      "phase": "Bound"
    }
  }
}

GET /services/:service_code/:environment_name/persistentvolumeclaims/:id

Retrieve a persistent volume claim and all its info in a given environment.

Attributes
id string	The id of the persistent volume claim. This is the name and namespace of the resource.
metadata object	The metadata of the persistent volume claim.
spec object	The specification of the persistent volume claim.
spec.accessModes string	The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.resources.requests.storage string	The requested storage capacity of the persistent volume.
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status object	The status of the persistent volume claim.
status.phase string	The claim is in one of the following phases: Pending, Bound, Lost or Terminating.
status.accessModes string	The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
status.capacity.storage string	The allocated storage capacity.

Create a persistent volume claim

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims"
  Content-Type: application/json
   {
      "apiVersion": "v1",
      "kind": "PersistentVolumeClaim",
      "metadata": {
         "name": "small-pvc",
         "namespace": "default"
      },
      "spec": {
         "accessModes": [
            "ReadWriteOnce"
         ],
         "resources": {
            "requests": {
               "storage": "10G"
            }
         }
      }
   }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/persistentvolumeclaims

Create a persistent volume claim in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the persistent volume claim.
metadata object	The metadata of the persistent volume claim.
metadata.name string	The name of the persistent volume claim.
spec object	The spec for the persistent volume claim.
spec.accessModes array	A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany.
spec.resources.requests.storage string	Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.

Optional Attributes
metadata.namespace string	The namespace in which the pod is created, if not specified will create the claim in default.
spec.storageClassName string	The storage class for the persistent volume claim, will use the default if not specified.
spec.resources.limits object	Limits describe the maximum number of storage resources allowed.

Return value:

Attributes
taskId string	The id corresponding to the create persistent volume claim task.
taskStatus string	The status of the operation.

Replace a persistent volume claim

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/my-persistent-volume-claim/default"
  Content-Type: application/json
  {
    "id": "pv-claim-name/default",
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
        "name": "pv-claim-name",
        "namespace": "default"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "resources": {
            "requests": {
                "storage": "1Gi"
            }
        },
        "storageClassName": "standard",
        "volumeName": "persistentvolumes-name",
        "dataSource": "dataSource"
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/persistentvolumeclaims/:id

Replace a persistent volume claim in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the claim.
metadata object	The metadata of the claim.
metadata.name string	The name of the claim.
spec object	The specification used to replace and run the claim.
spec.accessModes string	The desired access modes the volume should have.
spec.resources.requests.storage string	The size of the claim.
spec.storageClassName string	The name of the StorageClass required by the claim.
spec.volumeName string	The binding reference to the PersistentVolume backing this claim. Only required if claim is bound.

Optional Attributes
spec.volumemode string	What type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec.
spec.dataSource string	This field can be used to specify either: an existing VolumeSnapshot object, an existing PVC or an existing custom resource/object that implements data population.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace persistent volume claim task.
taskStatus string	The status of the operation.

Delete a persistent volume claim

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/persistentvolumeclaims/:id

Delete a perstent volume claim from a given environment.

Attributes
taskId string	The id corresponding to the delete persistent volume claim task.
taskStatus string	The status of the operation.

Access control

Service accounts

List service accounts

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts"

The above command returns a JSON structured like this:

{
      "metadata": {
        "name": "vpnkit-controller",
        "namespace": "kube-system",
        "selfLink": "/api/v1/namespaces/kube-system/serviceaccounts/vpnkit-controller",
        "uid": "b9afa8a8-3d64-4605-959f-12bb5c6cfba2",
        "resourceVersion": "481",
        "creationTimestamp": "2020-09-18T14:47:48Z",
        "annotations": {
          "kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ServiceAccount\",\"metadata\":{\"annotations\":{},\"name\":\"vpnkit-controller\",\"namespace\":\"kube-system\"}}\n"
        }
      },
      "secrets": [
        {
          "name": "vpnkit-controller-token-hl674"
        }
      ]
    }
  ]
}

GET /services/:service_code/:environment_name/serviceaccounts

Retrieve a list of all service accounts in a given environment.

Attributes
id string	The id of the service account.
metadata.annotations map	The annotations of the service account.
metadata object	The metadata of the service account.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace in which the service account is created.
metadata.uid object	The UUID of the service account.
metadata.secrets List<object>	The secrets of the service account.
secretsSize integer	The number of secrets of the service account.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a service account

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/serviceaccount-name/serviceaccount-namespace"

The above command returns a JSON structured like this:

{
  "data": {
            "id": "default",
            "age": "1w5d",
            "secretsSize": 1,
            "metadata": {
              "creationTimestamp": "2020-09-18T10:46:40.000-04:00",
              "name": "default",
              "namespace": "default",
              "uid": "80a0de4d-a187-44c3-b691-1481220a5817"
            },
            "secrets": [
              {
                "name": "default-token-lrth9"
              }
            ]
          },
          "fieldTransitions": {},
          "operations": []
        }

GET /services/:service_code/:environment_name/serviceaccounts/:id

Retrieve a service account and all its info in a given environment.

Attributes
id string	The id of the service account.
metadata object	The metadata of the service account.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace in which the service account is created.
metadata.uid object	The UUID of the service account.
metadata.secrets List<object>	The secrets of the service account.
secretsSize integer	The number of secrets of the service account.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a service account

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "metadata": {
        "name": "service-account-name",
        "namespace": "default"
    }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/serviceaccounts

Create a service account in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the service account.
metadata object	The metadata of the service account.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace of the service account.

Return value:

Attributes
taskId string	The id corresponding to the create service account task.
taskStatus string	The status of the operation.

Replace a service account

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/service-account-name/namespace-name"
  Content-Type: application/json
  {
    "metadata": {
        "name": "service-account-name",
        "namespace": "namespace-name"
    }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/serviceaccounts/:id

Replace a service account in a given environment.

Required Attributes
metadata object	The metadata of the service account.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace of the service account.

Return value:

Attributes
taskId string	The id corresponding to the create service account task.
taskStatus string	The status of the operation.

Delete a service account

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/my-service-account/my-namespace"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/serviceaccounts/:id

Delete a service account from a given environment.

Attributes
taskId string	The id corresponding to the delete service account task.
taskStatus string	The status of the operation.

Roles

List (namespace) Roles

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "role-id",
            "age": "1w4d",
            "metadata": {
                "creationTimestamp": "2020-09-18T10:01:26.000-04:00",
                "name": "kubeadm:bootstrap-signer-clusterinfo",
                "namespace": "kube-public",
                "uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a46"
            },
            "rules": [
                {
                    "apiGroups": [],
                    "resourceNames": [],
                    "resources": [],
                    "verbs": []
                }
            ]
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/roles

Retrieve a list of all roles in a given environment.

Attributes
id string	The id of the role.
metadata object	The metadata of the role.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the role.
metadata.namespace string	The namespace in which the role is created.
metadata.uid object	The UUID of the role.
rules array	The array of rules associated with this role.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a role

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/role-name/role-namespace"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "kubeadm:bootstrap-signer-clusterinfo",
        "age": "1w4d",
        "apiVersion": "rbac.authorization.k8s.io/v1",
        "kind": "Role",
        "metadata": {
            "creationTimestamp": "2020-09-18T10:01:26.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a47"
        },
        "rules": [
            {
                "apiGroups": [],
                "resourceNames": [],
                "resources": [],
                "verbs": []
            }
        ]
    }
}

GET /services/:service_code/:environment_name/roles/:id

Retrieve a role and all its info in a given environment.

Attributes
id string	The id of the role.
apiVersion string	The API version used to retrieve this role.
metadata object	The metadata of the role.
rules array	The array of rules associated with this role.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a role

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles"
  Content-Type: application/json
  {
   "apiVersion": "rbac.authorization.k8s.io/v1",
   "kind": "Role",
   "namespace": "default",
   "name": "test-name",
   "metadata": {
      "namespace": "default",
      "name": "test-name"
   },
   "rules": [
      {
         "apiGroups": [
            ""
         ],
         "resources": [
            "resource"
         ],
         "verbs": [
            "get",
            "watch"
         ]
      }
   ]
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/roles

Create a role in a given environment.

Attributes
id string	The id of the role.
apiVersion string	The API version used to create this role.
metadata.name string	The name of the role.
metadata.namespace string	The namespace of the role.
rules array	The array of rules associated with this role.

Return value:

Attributes
taskId string	The id corresponding to the create role task.
taskStatus string	The status of the operation.

Replace a role

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/role-name/namespace-name?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "metadata": {
        "name": "role-name",
        "namespace": "namespace-name"
    }
    "rules": [
      {
         "apiGroups": [
            ""
         ],
         "resources": [
            "resource"
         ],
         "verbs": [
            "get",
            "watch",
            "..."
         ]
      }
   ]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id

Replace a role in a given environment.

Required Attributes
metadata object	The metadata of the role.
metadata.name string	The name of the role.
metadata.namespace string	The namespace of the role.
metadata.namespace string	The namespace of the role.

Optional Attributes
rules array	The array of rules associated with this role.

Return value:

Attributes
taskId string	The id corresponding to the replace role operation.
taskStatus string	The status of the operation.

Delete a role

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/default-token-xxxmt/default"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/roles/:id

Delete a roles from a given environment.

Attributes
taskId string	The id corresponding to the delete role task.
taskStatus string	The status of the operation.

Role bindings

List role bindings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings"

The above command returns a JSON structured like this:

{

    "data": {
        "entity": {
          "id": "kubeadm:bootstrap-signer-clusterinfo",
          "age": "1w5d",
          "metadata": {
            "creationTimestamp": "2020-09-18T10:46:32.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
          },
          "roleRef": {
            "apiGroup": "rbac.authorization.k8s.io",
            "kind": "Role",
            "name": "kubeadm:bootstrap-signer-clusterinfo"
          },
          "subjects": [
            {
              "apiGroup": "rbac.authorization.k8s.io",
              "kind": "User",
              "name": "system:anonymous"
            }
          ]
        },
        "fieldTransitions": {},
        "operations": []
      },
}

GET /services/:service_code/:environment_name/rolebindings

Retrieve a list of all role bindings in a given environment.

Attributes
id string	The id of the role binding.
metadata object	The metadata of the role binding.
metadata.creationTimestamp string	The date of creation of the role binding as a string.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace in which the role binding is created.
metadata.uid object	The UUID of the role binding.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a role binding

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/rolebinding-name/rolebinding-namespace"

The above command returns a JSON structured like this:

{

    "data": {

          "id": "kubeadm:bootstrap-signer-clusterinfo",
          "age": "1w5d",
          "metadata": {
            "creationTimestamp": "2020-09-18T10:46:32.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
          },
          "roleRef": {
            "apiGroup": "rbac.authorization.k8s.io",
            "kind": "Role",
            "name": "kubeadm:bootstrap-signer-clusterinfo"
          },
          "subjects": [
            {
              "apiGroup": "rbac.authorization.k8s.io",
              "kind": "User",
              "name": "system:anonymous"
            }
          ]
        },
        "fieldTransitions": {},
        "operations": []
      },
}

GET /services/:service_code/:environment_name/rolebindings/:id

Retrieve a role binding and all its info in a given environment.

Attributes
id string	The id of the role binding.
apiVersion string	The API version used to retrieve this role binding.
metadata object	The metadata of the role binding.
subjects array	The array of subjects associated with this role binding.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a role binding

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings"
  Content-Type: application/json
  {
    "kind": "Rolebinding",
    "metadata": {
        "name": "rolebinding-name",
        "namespace": "namespace-name"
    },
    "roleRef": {
        "apiGroup": "rbac.authorization.k8s.io",
        "kind": "Role",
        "name": "role-name"
    },
    "subjects": [
        {
            "kind": "ServiceAccount",
            "name": "service-account-name",
            "namespace": "service-account-namespace"
        },
        {
            "kind": "Group",
            "name": "group-name",
            "namespace": "group-namespace"
        },
        {
            "kind": "User",
            "name": "user-name",
        }

    ]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/rolebindings

Create a role binding in a given environment.

Required Attributes
metadata object	The metadata of the role binding.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts.

Return value:

Attributes
taskId string	The id corresponding to the create role binding task.
taskStatus string	The status of the operation.

Replace a role binding

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/rolebinding-name/namespace-name"
  Content-Type: application/json
  {
    "metadata": {
        "name": "service-account-name",
        "namespace": "namespace-name"
    },
    "roleRef": {
      "apiGroup": "",
      "kind": "Role",
      "name": "role-name"
    },
    "subjects": [
      {
        "kind": "ServiceAccount",
        "name": "default",
        "namespace": "default"
      },
      {
        "kind": "user",
        "name": "user1",
      }
    ]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/rolebindings/:id

Replace a role binding in a given environment.

Required Attributes
metadata object	The metadata of the role binding.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts.

Return value:

Attributes
taskId string	The id corresponding to the replace role binding operation.
taskStatus string	The status of the operation.

Delete a role binding

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/default-token-xxxmt/default"

The above command returns a JSON structured like this: json { "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b", "taskStatus": "PENDING" } DELETE /services/:service_code/:environment_name/rolebindings/:id

Delete a role binding from a given environment.

Attributes
taskId string	The id corresponding to the delete role binding task.
taskStatus string	The status of the operation.

Releases

List releases

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-namespace/my-cloudflare",
      "name": "my-cloudflare",
      "info": {
        "first_deployed": "2020-11-03T09:48:49.301166-05:00",
        "last_deployed": "2020-11-05T11:24:37.096888-05:00",
        "deleted": "",
        "description": "Upgrade complete",
        "status": "installed",
        "notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
      },
      "chart": {
        "metadata": {
          "name": "cloudflare-dyndns",
          "home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
          "sources": [
            "https://github.com/hotio/docker-cloudflare-ddns/",
            "https://github.com/billimek/billimek-charts"
          ],
          "version": "2.0.0",
          "description": "Dynamic DNS using Cloudflare's DNS Services",
          "keywords": [
            "cloudflare",
            "dynamicdns"
          ],
          "maintainers": [
            {
              "name": "billimek",
              "email": "jeff@billimek.com"
            }
          ],
          "icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
          "apiVersion": "v1",
          "appVersion": "1.0",
          "deprecated": false
        },
        "values": {
          "affinity": {},
          "cloudflare": {
            "detection_mode": "dig-google.com",
            "hosts": "somehosts",
            "log_level": 1.0,
            "record_types": "somerecordtypes",
            "sleep_interval": 300.0,
            "token": "sometoken",
            "user": "someuser",
            "zones": "somezones"
          },
          "image": {
            "pullPolicy": "Always",
            "repository": "hotio/cloudflare-ddns",
            "tag": "latest"
          },
          "nodeSelector": {},
          "replicaCount": 1.0,
          "resources": {},
          "tolerations": []
        }
      },
      "config": {
        "affinity": {},
        "cloudflare": {
          "detection_mode": "dig-google.com",
          "hosts": "somehosts",
          "log_level": 1.0,
          "record_types": "somerecordtypes",
          "sleep_interval": 300.0,
          "token": "sometoken",
          "user": "someuser",
          "zones": "somezones"
        },
        "image": {
          "pullPolicy": "Always",
          "repository": "hotio/cloudflare-ddns",
          "tag": "latest"
        },
        "nodeSelector": {},
        "replicaCount": 1.0,
        "resources": {},
        "tolerations": []
      },
      "version": 10,
      "namespace": "my-namespace",
      "keepHistory": false,
      "chartVersion": "cloudflare-dyndns / 2.0.0"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/releases

Or

GET /services/:service_code/:environment_name/releases?namespace=default

Retrieve a list of all releases in a given environment.

Optional
namespace string	The namespace to list the release. This needs the exact value.

Attributes
id string	The release id, of the form namespace/releaseName.
name string	The name of the release.
info object	The information about the release.
info.first_deployed string	The annotations of the pod.
info.last_deployed string	The date of creation of the pod as a string.
info.deleted string	The labels associated to the pod.
info.description string	The name of the pod.
info.status string	The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback.
info.notes string	The notes linked to the release.
chart object	The information related to the chart of used in the release.
chart.version string	The version of the chart.
chart.metadata object	The metadata associated to the chart.
chart.metadata.name string	The name of the chart.
chart.metadata.home string	The home URL for the chart.
chart.metadata.sources list	The list of source of the charts.
chart.metadata.version string	The version of the chart.
chart.metadata.description string	The description of the chart.
chart.metadata.keywords list	The list of keywords linked to the chart.
chart.metadata.maintainers list	The list of the maintainer contact information.
chart.metadata.icon string	The icon URL for the chart.
chart.metadata.appVersion string	The version of the application.
chart.metadata.deprecate bool	If the chart is deprecated or not of the application.
config object	All values that were used to install the release.
version string	The revision of the release.
namespace string	The namespace to which the release is installed.

The information is not totally returned in the list. We filter out the manifest portion. We also filter out the files and the templates of the chart details. This information will be present in the GET request for an individual release.

Get release

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/my-namespace/my-cloudflare"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "my-namespace/my-cloudflare",
    "name": "my-cloudflare",
    "info": {
      "first_deployed": "2020-11-03T09:48:49.301166-05:00",
      "last_deployed": "2020-11-05T19:44:46.775668959Z",
      "deleted": "",
      "description": "Upgrade complete",
      "status": "installed",
      "notes": "You can connect to the container running cloudflare-dyndns. To open a shell session in the pod run the following:\n..."
    },
    "chart": {
      "metadata": {
        "name": "cloudflare-dyndns",
        "home": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
        "sources": [
          "https://github.com/hotio/docker-cloudflare-ddns/",
          "https://github.com/billimek/billimek-charts"
        ],
        "version": "2.0.0",
        "description": "Dynamic DNS using Cloudflare's DNS Services",
        "keywords": [
          "cloudflare",
          "dynamicdns"
        ],
        "maintainers": [
          {
            "name": "billimek",
            "email": "jeff@billimek.com"
          }
        ],
        "icon": "https://www.cloudflare.com/img/cf-facebook-card.png",
        "apiVersion": "v1",
        "appVersion": "1.0",
        "deprecated": false
      },
      "templates": [
        {
          "name": "templates/NOTES.txt",
          "data": "WW91I...fScp"
        },
        {
          "name": "templates/_helpers.tpl",
          "data": "e3svKi...9Cg=="
        },
        {
          "name": "templates/deployment.yaml",
          "data": "YXBpVm...9Cg=="
        },
        {
          "name": "templates/secret.yaml",
          "data": "YXBpVmVy...X0="
        }
      ],
      "values": {
        "affinity": {},
        "cloudflare": {
          "detection_mode": "dig-google.com",
          "hosts": "somehosts",
          "log_level": 1.0,
          "record_types": "somerecordtypes",
          "sleep_interval": 300.0,
          "token": "sometoken",
          "user": "someuser",
          "zones": "somezones"
        },
        "image": {
          "pullPolicy": "Always",
          "repository": "hotio/cloudflare-ddns",
          "tag": "latest"
        },
        "nodeSelector": {},
        "replicaCount": 1.0,
        "resources": {},
        "tolerations": []
      },
      "files": [
        {
          "name": ".helmignore",
          "data": "IyBQYX...b2oK"
        },
        {
          "name": "README.md",
          "data": "IyBE..4K"
        }
      ]
    },
    "manifest": "---\n# Source: cloudflare-dyndns/templates/secret.yaml\napiVersion: v1\n...",
    "config": {
      "affinity": {},
      "cloudflare": {
        "detection_mode": "dig-google.com",
        "hosts": "somehosts",
        "log_level": 1.0,
        "record_types": "somerecordtypes",
        "sleep_interval": 300.0,
        "token": "sometoken",
        "user": "someuser",
        "zones": "somezones"
      },
      "image": {
        "pullPolicy": "Always",
        "repository": "hotio/cloudflare-ddns",
        "tag": "latest"
      },
      "nodeSelector": {},
      "replicaCount": 1.0,
      "resources": {},
      "tolerations": []
    },
    "version": 11,
    "namespace": "my-namespace",
    "keepHistory": false,
    "chartVersion": "cloudflare-dyndns / 2.0.0"
  }
}

GET /services/:service_code/:environment_name/releases/:id

Attributes
id string	The release id, of the form namespace/releaseName.
name string	The name of the release.
info object	The information about the release.
info.first_deployed string	The date the release was created.
info.last_deployed string	The date the release was last updated.
info.deleted string	The labels associated to the pod
info.description string	Description of the release's status.
info.status string	The status of the release. Possible values are unknown, installed, uninstalled, superseded, failed, uninstalling, pending-install, pending-upgrade, pending-rollback.
info.notes string	The notes linked to the release.
chart object	The information related to the chart used to install the release.
chart.version string	The version of the chart.
chart.metadata object	The metadata associated to the chart.
chart.metadata.name string	The name of the chart.
chart.metadata.home string	The home URL for the chart.
chart.metadata.sources list	The list of source of the charts.
chart.metadata.version string	The version of the chart.
chart.metadata.description string	The description of the chart.
chart.metadata.keywords list	The list of keywords linked to the chart.
chart.metadata.maintainers list	The list of the maintainer contact information.
chart.metadata.icon string	The icon URL for the chart.
chart.metadata.appVersion string	The version of the application.
chart.metadata.deprecate bool	If the chart is deprecated or not of the application.
chart.templates list	The list of templates contained inside the chart.
chart.templates.name string	The path name of the template inside the chart.
chart.templates.data string	The contents of the template. This is a base64 encoded string.
chart.files list	The list of files contained inside the chart. These are not YAML files unlike the templates.
chart.files.name string	The path name of the file inside the chart.
chart.files.data string	The contents of the file. This is a base64 encoded string.
manifest string	The YAML Kubernetes resources created by the Helm templating.
config object	All values that were used to install the release.
version string	The revision of the release.
namespace string	The namespace to which the release is installed.

Rollback release to previous revision

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=rollback"

The above command returns a JSON structured like this:

{
  "data": {
      "name": "aerospike-1579797954",
      "version": 8,
      "info": {
          "deleted": "",
          "description": "Rollback to 6",
          "status": "deployed",
          ...
      ...
  },
  "taskId": "13943961-4a2c-4439-b7c9-05113d3b593a",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/releases/:id?operation=rollback

Rollback a release in a given environment to the previous revision.

Attributes
data Object	The release object. See get release for a description of the release attributes.
taskId string	The task id related to the pod rollback.
taskStatus string	The status of the operation.

Upgrade release

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/my-namespace/my-aerospike?operation=upgrade"
   -d "request_body"

Request body examples:

// Change to the latest version of a chart
{
    "upgradeChart": {
        "name": "aerospike",
        "repository": {
            "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
        }
    }
}

// Change to a specific version of a chart
{
    "upgradeChart": {
        "name": "aerospike",
        "version": "4.9.0",
        "repository": {
            "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
        }
    }
}

// Change the values for the latest version
{
    "upgradeChart": {
        "name": "aerospike",
        "repository": {
            "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
        }
    },
    "upgradeValues": "\"replicaCount\": 3"
}

The above commands return JSON structured like this:

{
  "taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/releases/:id?operation=upgrade

Upgrade a release in a given environment.

Required
upgradeChart Object	The chart object that should be used to ugprade the release.
upgradeChart.name string	The chart name.
repository Object	The repository object to which the chart belongs.
repository.url string	The repository's URL.

Optional
upgradeChart.version string	The chart version that should be used to upgrade the chart. If none is provided, the latest is used.
upgradeChart.values string	YAML structured text that will overwrite the default values for the upgrade/installation of the chart.

Attributes
taskId string	The task id related to the pod upgrade.
taskStatus string	The status of the operation.

Uninstall a release

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/releases/pspensieri/aerospike-1579797954&operation=uninstall"
   -d "request_body"

Request body example:

{
  "keepHistory": true
}

The above command returns a JSON structured like this:

{
  "data": {
      "version": 0,
      "keepHistory": false
  },
  "taskId": "938f11b2-b37d-459e-8cf2-dea05c4d8f63",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/releases/:id?operation=uninstall

Uninstall a release in a given environment.

Optional
keepHistory bool	If true, will keep release history after uninstalling. Defaults to false.

Attributes
version string	The uninstalled release's revision. Revision 0 indicated it was uninstalled.
keepHistory string	The keepHistory value used when uninstalling the chart.
taskId string	The task id related to the pod uninstall.
taskStatus string	The status of the operation.

Charts

List charts

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/charts"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "helm-stable/aerospike",
      "name": "aerospike",
      "description": "A Helm chart for Aerospike in Kubernetes",
      "version": "0.3.3",
      "license": "",
      "deprecated": false,
      "repository": {
        "url": "https://kubernetes-charts.storage.googleapis.com",
        "name": "helm-stable",
        "kind": 0,
        "official": false,
        "displayName": "Stable",
        "repositoryId": "3cc327ae-9403-4521-9b71-f9a41d5f86c8",
        "organizationName": "helm",
        "verifiedPublisher": false,
        "organizationDisplayName": "Helm"
      },
      "packageId": "c4b6ad70-898d-4093-bec8-089d5f48daeb",
      "displayName": "",
      "normalizedName": "aerospike",
      "appVersion": "v4.5.0.5",
      "logoImageId": "50bcf132-ff98-4f9a-9e6a-0c0b06649e48",
      "logoImageUrl": "https://artifacthub.io/image/50bcf132-ff98-4f9a-9e6a-0c0b06649e48"
    }
  ],
  "metadata": {
    "pageSize": 50,
    "pageCurrent": 1,
    "recordCount": 148
  }
}

GET /services/:service_code/:environment_name/charts

Retrieve a list of all charts in a given environment. To get more chart details, such as available versions, the chart's readme and list of maintainers, see the GET request for an individual chart.

Attributes
id string	The id for the chart, of the form repositoryName/chartName.
name string	The chart name.
description string	The chart description.
version string	The latest chart version.
license string	The chart's license.
deprecated boolean	True if the chart is deprecated.
repository object	The chart's parent repository.
repoository.url string	The repository URL.
repository.name string	The repository name.
repository.kind integer	The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }.
repository.official boolean	True if it is an official repository. That is, if the publisher owns the software deployed by the package.
repository.displayName string	The repository's display name.
repository.repositoryId UUID	The UUID of the repository.
repository.organizationName string	The name of the organization that owns the repository.
repository.organizationDisplayName string	The display name of the organization that owns the repository.
repository.verifiedPublisher boolean	True if the publisher owns the repository.
packageId UUID	The UUID of the package, given by ArtifactHub.
displayName string	The chart's display name.
normalizedName string	The chart's normalized name.
appVersion string	The chart's app version.
logoImageId UUID	The UUID of the package's logo, given by ArtifactHub.
logoImageUrl string	The URL for the chart's logo.

Get chart

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/charts/k8s-at-home/cloudflare-dyndns"

The above command returns a JSON structured like this:

{
  "data": {
    "keywords": [
      "cloudflare",
      "dynamicdns"
    ],
    "maintainers": [
      {
        "name": "billimek",
        "email": "jeff@billimek.com"
      }
    ],
    "links": [
      {
        "url": "https://github.com/hotio/docker-cloudflare-ddns/",
        "name": "source"
      },
      {
        "url": "https://github.com/billimek/billimek-charts",
        "name": "source"
      }
    ],
    "homeUrl": "https://github.com/billimek/billimek-charts/tree/master/charts/cloudflare-dyndns",
    "availableVersions": [
      {
        "version": "1.0.0",
        "createdAt": 1576998322
      },
      {
        "version": "2.0.0",
        "createdAt": 1578688072
      }
    ],
    "readMe": "# Dynamic DNS using Cloudflare's DNS Services\n...",
    "id": "k8s-at-home/cloudflare-dyndns",
    "name": "cloudflare-dyndns",
    "description": "Dynamic DNS using Cloudflare's DNS Services",
    "version": "2.0.0",
    "license": "",
    "deprecated": false,
    "repository": {
      "url": "https://k8s-at-home.com/charts/",
      "name": "k8s-at-home",
      "kind": 0,
      "official": false,
      "displayName": "charts",
      "repositoryId": "9b40a3b3-ed2a-405f-8919-3b824d4f661d",
      "organizationName": "k8s-at-home",
      "verifiedPublisher": true,
      "organizationDisplayName": "k8s@home"
    },
    "packageId": "a6cd6148-977a-4852-8761-80234f39d90b",
    "displayName": "",
    "normalizedName": "cloudflare-dyndns",
    "appVersion": "1.0",
    "logoImageId": "3a0eac41-21b4-4a1b-b127-c7e70123eda8",
    "logoImageUrl": "https://artifacthub.io/image/3a0eac41-21b4-4a1b-b127-c7e70123eda8"
  }
}

GET /services/:service_code/:environment_name/charts/:id

Retrieve a specific chart in a given environment.

Attributes
id string	The id for the chart, of the form repositoryName/chartName.
name string	The chart name.
description string	The chart description.
version string	The latest chart version.
license string	The chart's license.
deprecated boolean	True if the chart is deprecated.
repository object	The chart's parent repository.
repoository.url string	The repository URL.
repository.name string	The repository name.
repository.kind integer	The repository kind, where {0: Helm chart, 1: Falco rule, 2: OPA policy, 3: OLM operator }.
repository.official boolean	True if it is an official repository. That is, if the publisher owns the software deployed by the package.
repository.displayName string	The repository's display name.
repository.repositoryId UUID	The UUID of the repository.
repository.organizationName string	The name of the organization that owns the repository.
repository.organizationDisplayName string	The display name of the organization that owns the repository.
repository.verifiedPublisher boolean	True if the publisher owns the repository.
packageId UUID	The UUID of the package, given by ArtifactHub.
displayName string	The chart's display name.
normalizedName string	The chart's normalized name.
appVersion string	The chart's app version.
logoImageId UUID	The UUID of the package's logo, given by ArtifactHub.
logoImageUrl string	The URL for the chart's logo.
keywords Array[string]	The chart's keywords.
maintainers Array[Object]	The names and emails of chart maintainers.
homeUrl Array[Object]	The chart's home URL.
availableVersions Array[Object]	The available chart versions and their created dates.

Install chart

curl --request POST \
  --url https://cloudmc_endpoint/api/v1/services/a_service/an_environment/charts \
  --header 'MC-Api-Key: your_api_key' \
  --data '{
    "namespace": "my-namespace",
    "releaseName": "my-aerospike",
    "name": "aerospike",
    "version": "5.0.0",
  "values": ""
    "repository": {
        "url": "https://aerospike.github.io/aerospike-kubernetes-enterprise"
    }
}'

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/charts

Install a chart in a given environment.

Required
namespace string	The namespace in which the chart will be installed.
releaseName string	The desired release name.
name string	The chart name.
repository object	The chart's parent repository from which it should be installed.
repoository.url string	The repository URL.

Optional
version string	The chart version to be installed. Defaults to the latest version if left blank.
values string	The values used to install the chart. Must be a valid Yaml format. If not provided, the chart's default values will be used.
insecureServer boolean	True if accessing the chart requires an unsecured connection.

Azure plugin

The Azure plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of Azure.

Compute

Instances

Deploy and manage your instances.

List instances

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server",
      "name": "example-small-server",
      "machineType": "Standard_B1ls",
      "numberOfCores": 2,
      "memoryInGB": 1.75,
      "imagePublisher": "LinuxPublisher",
      "imageOffer": "CoreOS",
      "imageSku": "Alpha",
      "imageVersion": "1000.0.0",
      "osType": "Linux",
      "displayImage": "CoreOS - Alpha",
      "region": "canadacentral",
      "privateIp": "10.0.0.4",
      "macAddress": "00-0D-3A-84-0B-EF",
      "subnetName": "default",
      "networkName": "vn_root_qyg",
      "supportsPremiumIO": true,
      "supportsUltraIO": false,
      "attachableDiskSlots": 2,
      "usedLuns": [1],
      "powerState": "PowerState/running",
      "displayPowerState": "running",
      "networkInterfaces": [
        {
          "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkInterfaces/nicexample",
          "name": "nicexample",
          "primary": true
        }
      ],
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/instances

Retrieve a list of all instances in a given environment.

Attributes
id string	The id of the instance. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Compute/virtualMachines/:instanceName.
name string	The name of the instance.
machineType string	The type of machine assigned for this instance.
numberOfCores int	The number of cores provisioned for this instance. This is determined by the machine type.
memoryInGB int	The number of memory in GB provisioned for this instance. This is determined by the machine type.
imagePublisher string	The publisher of the instance used to create the instance.
imageOffer string	The image offer that was used to create the instance.
imageSku string	The image SKU that was used to create the instance.
imageVersion string	The image version that was used to create the instance.
displayImage string	Displayable value of the image information.
osType string	The OS type of the instance. This can be either Windows or Linux.
region string	The region in which the instance is located.
privateIp string	The private ip address assigned to the instance.
internalFqdn string	The internal FQDN assigned to the instance.
macAddress string	The MAC address assigned to the instance.
subnetName string	The name of the subnet that the instance is part of.
networkName string	The name of the network that the instance is part of.
supportsPremiumIO boolean	If the instance supports Premium disks. This is fixed by the machine type.
supportsUltraIO boolean	If the instance supports Ultra disks. This is fixed by the machine type.
attachableDiskSlots integer	The number of managed disks that can be attached to the instance. This is fixed by the machine type.
usedLuns array	An array of all the LUNs associated with the managed disks attached to this instance.
publicIp string	The public ip address assigned to the instance.
powerState string	The status of the instance. One of the following values: PowerState/running, PowerState/deallocating, PowerState/deallocated, PowerState/starting, PowerState/stopped, PowerState/stopping and PowerState/unknown.
displayPowerState string	The status of the instance. One of the following values: running, deallocating, deallocated, starting, stopped, stopping and unknown.
networkInterfaces list	A list of network interfaces of the instance. Contains fields: id, name, primary.

Retrieve an instance

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server",
    "name": "example-small-server",
    "machineType": "Standard_B1s",
    "numberOfCores": 2,
    "memoryInGB": 1.75,
    "imagePublisher": "LinuxPublisher",
    "imageOffer": "CoreOS",
    "imageSku": "Alpha",
    "imageVersion": "1000.0.0",
    "osType": "Linux",
    "displayImage": "CoreOS - Alpha",
    "region": "canadacentral",
    "privateIp": "10.0.0.4",
    "macAddress": "00-0D-3A-0B-F2-96",
    "subnetName": "default",
    "networkName": "vn_root_qyg",
    "supportsPremiumIO": true,
    "supportsUltraIO": false,
    "attachableDiskSlots": 2,
    "usedLuns": [],
    "powerState": "PowerState/running",
    "displayPowerState": "running",
    "networkInterfaces": [
      {
        "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkInterfaces/nicexample",
        "name": "nicexample",
        "primary": true
      }
    ],
  }
}

GET /services/:service_code/:environment_name/instances/:id

Retrieve an instance in a given environment.

Attributes
id string	The id of the instance. This is a canonized id from azure which is the form of /subscriptions/${subscriptionid}/resourceGroups/${resourcegroup}/providers/Microsoft.Compute/virtualMachines/${instanceName}.
name string	The name of the instance.
machineType string	The type of machine assigned for this instance.
numberOfCores int	The number of cores provisioned for this instance. This is determined by the machine type.
memoryInGB int	The number of memory in GB provisioned for this instance. This is determined by the machine type.
imagePublisher string	The publisher of the instance used to create the instance.
imageOffer string	The image offer that was used to create the instance.
imageSku string	The image SKU that was used to create the instance.
imageVersion string	The image version that was used to create the instance.
osType string	The OS type of the instance. This can be either Windows or Linux.
displayImage string	Displayable value of the image information.
region string	The region in which the instance is located.
privateIp string	The private ip address assigned to the instance.
internalFqdn string	The internal FQDN assigned to the instance.
macAddress string	The MAC address assigned to the instance.
subnetName string	The name of the subnet that the instance is part of.
networkName string	The name of the network that the instance is part of.
supportsPremiumIO boolean	If the instance supports Premium disks. This is fixed by the machine type.
supportsUltraIO boolean	If the instance supports Ultra disks. This is fixed by the machine type.
attachableDiskSlots integer	The number of managed disks that can be attached to the instance. This is fixed by the machine type.
usedLuns array	An array of all the LUNs associated with the managed disks attached to this instance.
publicIp string	The public ip address assigned to the instance.
powerState string	The status of the instance. One of the following values: PowerState/running, PowerState/deallocating, PowerState/deallocated, PowerState/starting, PowerState/stopped, PowerState/stopping and PowerState/unknown.
displayPowerState string	The status of the instance. One of the following values: running, deallocating, deallocated, starting, stopped, stopping and unknown.
networkInterfaces list	A list of network interfaces of the instance. Contains fields: id, name, primary.

Create an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances"

Request body examples:

// Create an instance using ssh key authentication
{
  "name": "new-server",
  "machineType": "Standard_B1ls",
  "imagePublisher": "CoreOS",
  "imageOffer": "CoreOS",
  "imageSku": "Stable",
  "imageVersion": "1010.5.0",
  "region": "canadacentral",
  "subnet": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/virtualNetworks/vn_example_lud/subnets/default",
  "username": "johndoe",
  "sshkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCguvgDRuUF/wijOJCNmYlQHujCmUHl/i0Ubos4nHy5uCBdn1LGF+PG3TpJqO1LUWqpHaPl4yN7bpsdXyq6a9nxe0C1bQ4FK6P5qm0X320uvqv34jwTPsIbnhw9I317df+xJyXXsL/P5vS4ULPMC5UZjWm4BYe7did4zmXXhA/zmLY6cUg19sZp5r5SUQcf5xHAqO3cQVZwzBhBMwroflZZ59zNpxy+xXPBqC3IdusF2yTDW7bwCQHESUOsd9XhwrzCB+1wETKjLpk0wkWj8G2j1pkKGRpv60QcG85lbZvQAg54v3HYD7fVJCaz9gJJoiyRBnqQ6XVxam5bZgiMKa0J johndoe@machine.local"
}

// Create an instance using password authentication
{
  "name": "new-server",
  "machineType": "Standard_B1ls",
  "imagePublisher": "CoreOS",
  "imageOffer": "CoreOS",
  "imageSku": "Stable",
  "imageVersion": "1010.5.0",
  "region": "canadacentral",
  "subnet": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/virtualNetworks/vn_example_lud/subnets/default",
  "username": "johndoe",
  "password": "SomePassw0rdVal!d"
}

POST /services/:service_code/:environment_name/instances

Create a new instance.

Required
name string	The name of the instance. The name cannot exceed 64 characters.
machineType string	The type of machine assigned for this instance.
imagePublisher string	The image publisher from which the image is selected.
imageOffer string	The image offer that was used to create the instance.
imageSku string	The image SKU that was used to create the instance.
imageVersion string	The image version that was used to create the instance.
region string	The region in which the instance is located.
subnet string	The subnet id that the instance will be part of.
username string	The administrator username which will be created on the instance. It cannot be a reserve user such as admin, root or administrator and must not be more than 20 characters.

Optional
password string	The password of the administrator account. It must be between between 12 and 72 characters and must be a combination of 3 of the following patterns : Special characters, Uppercase, Lowercase and Numbers. The password is mandatory if the sshkey is not provided.
sshkey string	The ssh key public portion that will be assigned to the user on the machine. This cannot be used for a Windows based OS.
publicIpAddressId string	The fully qualified id of the public IP address to associate to the instance.

Delete an instance

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server"

DELETE /services/:service_code/:environment_name/instances/:id

Delete an existing instance.

Query Parameter
deleteOsDisk boolean	Will delete the OS disk attached to this instance. Default value is false.

Change machine type

A machine type determines the number of vCPUs and the size of the memory allocated to the instances.

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=resize"

Request body example:

{
  "machineType": "Standard_B1ls"
}

POST /services/:service_code/:environment_name/instances/:id?operation=resize

Update the machine type for the existing instance.

Required
machineType string	The new machine type to assign to the instance.

Reset password

Reset the administrator password on Windows or Linux instances.

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=reset_password"

Request body example:

{
  "password": "SomePassw0rdVal!d"
}

POST /services/:service_code/:environment_name/instances/:id?operation=reset_password

For Linux instances, reset the administrator account. For Windows instances, reset the administrator account and reset the Remote Desktop service configuration.

Optional
password string	The password of the administator account. It must be between between 12 and 72 characters and must be a combination of 3 of the following patterns : Special characters, Uppercase, Lowercase and Numbers. If not provided, a new password is generated.

Start an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=start"

POST /services/:service_code/:environment_name/instances/:id?operation=start

Start an existing instance. The instance must be in the power state PowerState/deallocated or PowerState/stopped for this operation to work.

Stop an instance

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/instances/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Compute/virtualMachines/example-small-server?operation=stop"

POST /services/:service_code/:environment_name/instances/:id?operation=stop

Stop an existing instance. The instance must be in either the power state PowerState/running or PowerState/starting status for this operation to work.

Attach a disk (instance side)

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
 "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/instances/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/instances/{instanceName}?operation=attach_disk"

Request body example:

{
  "diskToAttach" : "disktest1",
  "diskLun": 10
}

The above command returns a JSON structured like this:

{
  "taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/instances/:id?operation=attach_disk

Required
diskToAttach String	The Id of the disk that you want to be attached to the instance.
diskLun Integer	The logic unit number of a disk. Can only be between 1 and 63 inclusive.

Regions

A region is location where Azure resources are physically deployed. They can be whitelisted in the service configuration for an Azure connection in CloudMC.

List regions

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/regions"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "name": "eastasia"
    },
    {
      "name": "eastus"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/regions

Retrieve a list of all regions enabled.

Attributes
name string	The name of the region.

Retrieve a region

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/regions/useast"

The above command returns a JSON structured like this:

{
  "data": {
    "name": "eastus"
  }
}

GET /services/:service_code/:environment_name/regions/:name

Retrieve a specific enabled region.

Attributes
name string	The name of the region.

Storage

Disks

Deploy and manage your disks.

For information regarding azure disks, please see azure docs.

List disks

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/disks"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/ssamadh-basic",
      "name": "ssamadh-basic",
      "type": "premium_lrs",
      "region": "southeastasia",
      "state": "unattached",
      "provisioningState": "succeeded",
      "creationDate": "2020-02-05T19:17:43.749Z",
      "sizeInBytes": 8589934592,
      "iops": 120,
      "throughputInMBps": 25,
      "dataDisk": true,
      "isAttachedToInstance": false
    },
    {
      "id": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
      "name": "the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
      "type": "premium_lrs",
      "osType": "Linux",
      "region": "eastasia",
      "instanceId": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/virtualMachines/the-sheep",
      "instance": "the-sheep",
      "state": "attached",
      "provisioningState": "succeeded",
      "creationDate": "2020-02-05T21:02:36.062Z",
      "sizeInBytes": 32213303296,
      "iops": 120,
      "throughputInMBps": 25,
      "dataDisk": false,
      "isAttachedToInstance": true
    },
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/disks

Retrieve a list of all the disks in a given environment.

Attributes
data array	A list of Azure disks. (See "Retrieve an Azure disk" API for the strucutre of each disk object)
metadata object	Consists of the meta information related to the returned disk list. The attribute recordCount contains the number of disks returned.

Retrieve an Azure disk

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4"

The above command returns a JSON structured like this:

{
  "id": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
  "name": "the-sheep_disk1_e93bd2519aac4c0cbe27c49aa928525e",
  "type": "premium_lrs",
  "osType": "Linux",
  "region": "eastasia",
  "instanceId": "/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/virtualMachines/the-sheep",
  "instance": "the-sheep",
  "state": "attached",
  "provisioningState": "succeeded",
  "creationDate": "2020-02-05T21:02:36.062Z",
  "sizeInBytes": 32213303296,
  "iops": 120,
  "throughputInMBps": 25,
  "dataDisk": false,
  "isAttachedToInstance": true
}

GET /services/:service_code/:environment_name/disks/:id

Retrieve a specific disk in a given environment.

Attributes
id string	The id of the disk. This is a canonized id from azure which is the form of /subscriptions/${subscriptionid}/resourceGroups/${resourcegroup}/providers/Microsoft.Compute/disks/${diskName}
name string	The display name of the disk
type string	The managed disk type. Can be one of the following: premium_lrs (Premium SSD), standard_lrs (Standard HDD), standardssd_lrs (Standard SSD) or ultrassd_lrs (Ultra SSD)
region string	The regional location in which the disk was instantiated
instanceId string	The id of the instance to which the disk is attached to. This is a canonized id from azure which is the form of /subscriptions/${subscriptionid}/resourceGroups/${resourcegroup}/providers/Microsoft.Compute/virtualMachines/${instanceName}
instance string	The name of the instance to which the disk is attached to (available only if the disk is attached to an instance)
state string	An indication of the state of the disk. Can be one of the following: Unattached, Attached, Reserved, ActiveSAS, ReadyToUpload, ActiveUpload
provisioningState string	An indication of the provisioning state of the disk (SUCCESS or FAILURE)
creationDate string	The date in which the disk was created
sizeInBytes long	The size of the disk in bytes
iops long	The number of IOPS allowed for this disk (only settable for UltraSSD disks). One operation can transfer between 4k and 256k bytes.
throughputInMBps long	The bandwidth allowed for this disk; only settable for UltraSSD disks. MBps means millions of bytes per second - MB here uses the ISO notation, of powers of 10.
dataDisk boolean	Indication of whether the disk is a DATA disk. If false then it's an OS disk
isAttachedToInstance boolean	An indication of whether the disk has been attached to an Azure instance

Create a disk

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body"
   "https://cloudmc_endpoint/api/v1/services/azure/example/disks"

Request body example:

{
  "name":"ad_root_smean",
  "region":"northeurope",
  "type":"ultrassd_lrs",
  "sizeGb":"200",
  "iops": "40",
  "throughputInMBps": "200"
}

The above command returns a JSON structured like this:

{
  "taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/disks

(Use the task API to get the status of the operation)

Create a disk in an environment.

Attributes
name string	The name of the azure disk. Supported characters for the name are a-z, A-Z, 0-9 and _; The maximum name length is 80 characters
region string	The azure region in which the disk is to be created. See list of regions here
type string	The managed disk type. Can be one of the following: premium_lrs, standard_lrs, standardssd_lrs, ultrassd_lrs
sizeGb string	The size of the disk
iops string	The number of read/write operations per second on the disk (Only supported for disks of type ultrassd_lrs)
throughputInMBps string	The throughput of the disk (Only supported for disks of type ultrassd_lrs)

Edit a disk

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body"
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4"

Request body examples:

{
  "type":"standardssd_lrs",
  "sizeGb":"200",
}

{
  "iops": "40",
  "throughputInMBps": "200"
}

The above commands return JSON structured like this:

{
  "taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/disks/:id

(Use the task API to get the status of the operation)

Edit a disk in an environment.

Optional
type string	The managed disk type. Can only be one of the following: premium_lrs, standard_lrs, standardssd_lrs Updating the type of an Ultra disk is not allowed Updating the type to ultrassd_lrs is also not allowed
sizeGb string	The size of the disk Disk size can only be increased during an update Updating the disk size of Ultra disks are not allowed
iops string	The number of read/write operations per second on the disk (Only supported for disks of type ultrassd_lrs)
throughputInMBps string	The throughput of the disk (Only supported for disks of type ultrassd_lrs)

Note: If the disk is attached to an instance, then the attached instance will be deallocated (removed from the host hypervisor) before the disk update and will be restored back to its original power state.

Delete a disk

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4"

DELETE /services/:service_code/:environment_name/disks/:id

Destroy an existing disk. A disk can only be deleted if it's not attached to an instance.

Detach a disk

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/disks/subscriptions/60a3c9eebe64-55c1-4b1d-969b-60a3c/resourceGroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.Compute/disks/the-sheep_disk1_c0cbe27c49aa928525e93bd2519aac4?operation=detach"

POST /services/:service_code/:environment_name/disks/:id?operation=detach

Detach an existing disk from a given instance.

Attach a disk (disk side)

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/disks/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Compute/disks/{diskName}?operation=attach"

Request body examples:

{
  "instance" : "cool-instance",
}

{
  "instance" : "cool-instance",
  "lun" : 10
}

The above command returns a JSON structured like this:

{
  "taskId": "802c5ae0-8431-47dc-9abe-7e10a9badddc",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/disks/:id?operation=attach

Attach a disk to an instance.

Optional
lun Integer	The logic unit number of a disk. Can only be between 1 and 63 inclusive. If the LUN is not specified it will default to the first available LUN for that instance.

Networking

Virtual Networks

A virtual network is an isolated network where you can place groups of resources, such as instances.

List virtual networks

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/networks"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/virtualNetworks/sample-network",
      "name": "sample-network",
      "region": "canadacentral",
      "provisioningState": "Succeeded",
      "addressSpace": [
        "10.2.0.0/16"
      ]
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/networks

Retrieve a list of all virtual networks in an environment.

Optional query parameters
subnetList boolean	If set to true, it will also include the subnet information in the list.

Attributes
id string	The id associated to the virtual network. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName
name string	The name of the virtual network
region string	The region in which the virtual network is located
provisioningState string	The provisioning state of the virtual network. Possible values are : Succeeded, Updating, Deleting and Failed
addressSpace list	List of address space that are covered by this virtual network

Create virtual networks

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body"
   "https://cloudmc_endpoint/api/v1/services/azure/example/networks"

Request body example:

{
    "name": "simpleNetwork",
    "region" : "canadaeast",
    "addressSpace": "10.0.0.0/16",
    "subnetName": "default",
    "subnetAddressPrefix": "10.0.0.0/16"
}

POST /services/:service_code/:environment_name/networks

Create a virtual network in an environment.

Attributes
name string	The name of the virtual network
region string	The region in which the virtual network is located
addressSpace string	The first address range (IPV4 CIDR format) that will be covered by this virtual network
subnetName string	The first subnet name within this virtual network
subnetAddressPrefix string	The first subnet address range (IPV4 CIDR format) within this virtual network
networkSecurityGroupId string	The id of the network security group for the subnet, can also enter NONE or omit the field.

Subnets

A subnet is a child of a virtual network. It is a subset of a network in which IP addresses point to the same group.

List subnets

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/subnets"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "addressPrefix": "10.1.2.0/24",
      "parentNetworkId": "/subscriptions/:subscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet",
      "parentNetworkName": "example-vnet",
      "allocatedIpAddresses": 3,
      "availableAddresses": 248,
      "totalNumberIps": 251,
      "id": "/subscriptions/:subscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet",
      "region": "eastus",
      "name": "example-subnet"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/subnets

Retrieve a list of all subnets in an environment. If the network filter is included, the response bodies will contain additional details specified below.

Query parameters
network_id string	The id for the network who's subnets you're fetching. Only subnets of the passed network will be returned.

Attributes
id string	The id associated to the subnet. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName/subnets/:subnetName
parentNetworkId string	The id for the parent network.
parentNetworkName string	The name for the parent network.
name string	The name of the subnet.
region string	The region in which the parent of the subnet is located.
allocatedAddresses int	The number of allocated addresses in the subnet.
availableAddresses int	The number of available ip addresses in the subnet.
totalNumberIps int	The total number of ip addresses in the address space of the subnet.

Additional Attributes: Network filter included
networkSecurityGroupId string	The id of the network security group for the subnet, if it exists.
networkSecurityGroupName string	The name of the network security group for the subnet, if it exists.
nics list	A list of nics associated to the subnet.
nics.name string	The name of the nic.
nics.primaryPrivateIp string	The primary private ip for the nic.
nics.id string	The id for the nic.
nics.subnetName string	The name for the subnet to which to the nic belongs.
nics.networkName string	The name for the network to which to the nic belongs.

Retrieve a subnet

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/subnets/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet"

The above command returns a JSON structured like this:

{
  "data": {
    "addressPrefix": "10.1.2.0/24",
    "parentNetworkId": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet",
    "parentNetworkName": "example-vnet",
    "allocatedIpAddresses": 3,
    "availableAddresses": 248,
    "totalNumberIps": 251,
    "id": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet",
    "region": "eastus",
    "name": "example-subnet",
    "networkSecurityGroupName": "test-rg",
    "nics": [
      {
        "name": "sample-nic",
        "subnetName": "example-subnet",
        "subnetName": "example-vnet",
        "primaryPrivateIp": "10.1.2.4",
        "id": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/networkInterfaces/virtualNetworks/sample-nic"
      }
    ]
  }
}

GET /services/:service_code/:environment_name/subnets/:subnet_id

Retrieve a specific subnet by id.

Attributes
addressPrefix string	The IPv4 CIDR representing the address range for the subnet.
id string	The id associated to the subnet. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName/subnets/:subnetName
parentNetworkId string	The id for the parent network.
parentNetworkName string	The name for the parent network.
name string	The name of the subnet.
region string	The region in which the parent of the subnet is located.
allocatedAddresses int	The number of allocated addresses in the subnet.
availableAddresses int	The number of available ip addresses in the subnet.
totalNumberIps int	The total number of ip addresses in the address space of the subnet.
networkSecurityGroupId string	The id of the network security group for the subnet, if it exists.
networkSecurityGroupName string	The name of the network security group for the subnet, if it it exists.
nics list	A list of nics associated to the subnet.
nics.name string	The name of the nic.
nics.primaryPrivateIp string	The primary private ip for the nic.
nics.id string	The id for the nic.
nics.subnetName string	The name for the subnet to which to the nic belongs.
nics.networkName string	The name for the network to which to the nic belongs.

Create a subnet

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/subnets"

Request body example:

{
  "name": "default",
  "addressPrefix": "10.0.1.0/24",
  "parentNetworkId": "/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet"
}

POST /services/:service_code/:environment_name/subnets

Create a new subnet.

Required
name string	The name of the subnet. The name cannot exceed 80 characters.
addressPrefix string	The portion of the parent network's address space (IPV4 CIDR format) allocated to the subnet. The range cannot overlap with other subnets. The smallest range you can specify is /29.
parentNetworkId string	The subnet's parent network id.

Optional
networkSecurityGroupId string	The id for the network security group you want to associate the subnet to, can be NONE.

Update a Subnet

curl -X PUT \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/subnets/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet"

Request body example:

{
  "addressPrefix":"This is my updated template description"
}

PUT /services/:service_code/:environment_name/subnets/:subnet_id

Update a subnet.

Optional
addressPrefix string	The portion of the parent network's address space (IPV4 CIDR format) allocated to the subnet. The range cannot overlap with other subnets. The smallest range you can specify is /29. Can only be updated if it is contained within the range of the parent network and if no resources are attached to the subnet.
networkSecurityGroupId string	The id for the network security group you want to associate the subnet to, NONE if you want to detach the current network security group.

Delete a subnet

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/subnets/subscriptions/mySubscription/resourceGroups/myResourceGroup/providers/Microsoft.Network/virtualNetworks/example-vnet/subnets/example-subnet"

DELETE /services/:service_code/:environment_name/subnets/:subnet_id

Deletes a specific subnet by id.

Attributes
id string	The id associated to the subnet. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/virtualNetworks/:networkName/subnets/:subnetName

Network Security Groups

A network security group is a group of security rules that allow or deny inbound network traffic to, or outbound network traffic from, several types of Azure resources, including Azure virtual networks.

List network security groups

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/networksecuritygroups"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group",
      "name": "sample-network-security-group",
      "region": "canadacentral",
      "provisioningState": "Succeeded",
       "defaultSecurityRules": [
        {
          "name": "SampleRule",
          "id": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group/defaultSecurityRules/SampleRuleInBound",
          "direction": "Inbound"
        }],
      "customSecurityRules": [],
      "numberInbound": 3,
      "numberOutbound": 3,
      "numberAssociatedSubnets": 0,
      "numberAssociatedNetworkInterfaces": 0
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/networksecuritygroups

Retrieve a list of all network security groups in an environment.

Attributes
id string	The id associated to the network security group. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName
name string	The name of the network security group.
region string	The region in which the network security group is located
provisioningState string	The provisioning state of the network security group. Possible values are : Succeeded, Updating, Deleting and Failed
defaultSecurityRules List	The default security rules of network security group
customSecurityRules List	A collection of security rules of the network security group
numberInbound int	The number of security rules (default and custom) which are inbound
numberOutbound int	The number of security rules (default and custom) which are outbound
numberAssociatedSubnets int	The number of subnets associated with this network security group
numberAssociatedNetworkInterfaces int	The number of network interfaces associated with this network security group

Create a network security group

curl -X POST \
  'http://cloudmc_endpoint/v1/services/azure/my-azure/networkSecurityGroups' \
  -H 'mc-api-key: your_api_key' \
  -d '{
    "name": "network-security-group", 
    "region": "eastus"
}'

POST /services/:service_code/:environment_name/networkSecurityGroups

Create a new network security group.

Required
name string	The name of the network security group. The name cannot exceed 64 characters
region string	The region in which the network security group is located

Delete a network security group

curl -X DELETE \
  'http://cloudmc_endpoint/v1/services/azure/my-azure/networkSecurityGroups/subscriptions/6b6a1f27-55c1-4b1d-969b-60a3c9eebe64/resourceGroups/azure-system-co-cloudmc-eastus/providers/Microsoft.Network/networkSecurityGroups/test' \
  -H 'mc-api-key: your_api_key'

DELETE /services/:service_code/:environment_name/networkSecurityGroups/:id

Delete an existing network security group.

Security Rules

A security rule in Azure is a filter which controls both inbound and outbound traffic on a network security group attacted to the ressource that receives the traffic.

List security rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/securityrules"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group/defaultSecurityRules/SampleRuleInBound",
      "name": "SampleRule",
      "direction": "Inbound",
      "access": "Deny",
      "priority": 110,
      "protocol": "Udp",
      "sourcePortRanges": [
        "1024"
      ],
      "sources": [
        "0.0.0.1",
        "10.0.0.0/32"
      ],
      "destinationPortRanges": [
        "8080"
      ],
      "destinations": [
        "10.0.0.0/16"
      ],
      "securityGroupId": "/subscriptions/:subscription/resourceGroups/:resourceGroup/providers/Microsoft.Network/networkSecurityGroups/sample-network-security-group"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/securityrules

Retrieve a list of all security rules in an environment.

Query parameters
security_group_id string	The id of the network security group in which we want to fetch the list of security rules.
direction string	Filter on the list of security rules. Either Inbound or Outbound. No value will passed will return a list with both included.

Attributes
id string	The id associated to the security rule. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/defaultSecurityRules/:securityRuleName if it is a default rule or /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/securityRule/:securityRuleName if it is a custom rule.
name string	The name of the security rule.
priority int	Rules are processed in priority order; the lower the number, the higher the priority. Values are between 100 and 4096.
direction string	Either Inbound or Outbound.
access string	Determine if rule is allowing or blocking trafic. Either Access or Deny.
protocol string	One of *, TCP, UDP and ICMP. * is allowing any protocol.
sourcePortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
sources List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.
destinationPortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
destinations List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.
securityGroupId String	The id of the network security group to which the rule belongs.

Retrieve a security rule

curl -X GET \
  -H 'mc-api-key: your_api_key' \
  "https://cloudmc_endpoint/api/v1/services/azure/example/securityrules/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkSecurityGroups/mySecurityGroup/securityRules/mySeccurityRule"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkSecurityGroups/mySecurityGroup/defaultSecurityRules/SampleRuleInBound",
    "name": "SampleRuleInBound",
    "direction": "Inbound",
    "access": "Allow",
    "priority": 65001,
    "protocol": "*",
    "sourcePortRanges": [],
    "destinationPortRanges": [],
    "destinationAddressPrefixes": [],
    "sourceAddressPrefixes": [
      "AzureLoadBalancer"
    ],
    "securityGroupId": "/subscriptions/:subscription/resourceGroups/:resourceGroup/providers/Microsoft.Network/networkSecurityGroups/sample-network-security-group"
  }
}

GET /services/:service_code/:environment_name/securityrules/:id

Retrieve a specific security rule by rule id.

Attributes
id string	The id associated to the security rule. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/defaultSecurityRules/:securityRuleName if the rule is a default security rule or /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/securityRules/:securityRuleName if the rule is a custom rule.
name string	The name of the security rule.
priority int	The priority of the security rule.
direction string	Either Inbound or Outbound.
access string	Determine if rule is allowing or blocking trafic. Either Access or Deny.
protocol string	One of *, TCP, UDP and ICMP. * is allowing any protocol.
sourcePortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
sources List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.
destinationPortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
destinations List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.
securityGroupId String	The id of the network security group to which the rule belongs.

Create a security rule

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body"
    "https://cloudmc_endpoint/api/v1/services/azure/example/securityrules"

Request body example:

{
  "securityGroupId": "/subscriptions/subscription/resourceGroups/example-system-azure-example/providers/Microsoft.Network/networksecuritygroups/sample-network-security-group",
  "name": "SampleRule",
  "priority": 110,
  "direction": "Inbound",
  "access": "Deny",
  "protocol": "Udp",
  "sourcePortRanges": [
    "1024"
  ],
  "sources": [
    "0.0.0.1",
    "10.0.0.0/32"
  ],
  "destinationPortRanges": [
    "8080"
  ],
  "destinations": [
    "10.0.0.0/16"
  ]
}

POST /services/:service_code/:environment_name/securityrules

Create a new network security rule in an existing security group.

Required
securityGroupId string	The id of the network security group in which we want to create the security rule.
name string	The name of the security rule.
priority int	Rules are processed in priority order; the lower the number, the higher the priority. Values are between 100 and 4096.
direction string	Either Inbound or Outbound.
access string	Determine if rule is allowing or blocking trafic. Either Access or Deny.
protocol string	One of *, TCP, UDP and ICMP. * is allowing any protocol.

Optional
sourcePortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
sources List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.
destinationPortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
destinations List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.

Delete a security rule

curl -X DELETE \
  -H 'mc-api-key: your_api_key' \
  "https://cloudmc_endpoint/api/v1/services/azure/example/securityrules/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/sample-network-security-group/securityRules/securityRule1"

DELETE /services/:service_code/:environment_name/securityrules/:id

Delete an existing security rule.

Edit a security rule

curl -X POST \
  -H 'mc-api-key: your_api_key' \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/azure/example/securityrules/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkSecurityGroups/mySecurityGroup/securityRules/mySecurityRule?operation=edit"

Request body example:

{
  "access": "Allow",
  "priority": 180,
  "protocol": "Tcp",
  "sourcePortRanges": [],
  "sources": [
    "10.0.0.0/24"
  ],
  "destinationPortRanges": [
    "8080"
  ],
  "destinations": [
    "192.168.99.0"
  ]
}

POST /services/:service_code/:environment_name/securityrules/:id?operation=edit

Update a specific security rule.

Attributes
id string	The id associated to the security rule. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/defaultSecurityRules/:securityRuleName if the rule is a default security rule or /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/networksecuritygroups/:networkSecurityGroupName/securityRules/:securityRuleName if the rule is a custom rule.
access string	Determine if rule is allowing or blocking trafic. Either Access or Deny.
priority int	The priority of the security rule.
protocol string	One of *, TCP, UDP and ICMP. * is allowing any protocol.
sourcePortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
sources List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.
destinationPortRanges List	This specifies on which ports traffic will be allowed or denied by this rule. If the list is empty then all values are included.
destinations List	List of IP address ranges or/and IP adresses. If the list is empty then all values are included.

Public IP addresses

Deploy and manage your public ip addresses.

List public IP addresses

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/publicipaddresses"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip",
      "name": "some-public-ip",
      "state": "DETACHED",
      "ipAddress": "52.122.12.1",
      "region": "eastus",
      "domainName": "somepublicip",
      "fqdn": "somepublicip.eastus.cloudapp.azure.com",
      "sku": "BASIC",
      "idleTimeout": 7,
      "allocationMethod": "DYNAMIC",
      "ipVersion": "IPV4"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/publicipaddresses

Retrieve a list of all public IP addresses in a given environment

Attributes
id string	The id of the public IP address. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/publicIPAddresses/:publicIpName.
name string	The name of the public IP address.
state string	The state of the public IP address. Possible state: ATTACHED, DETACHED, UPDATING, DELETING.
ipAddress string	The IP address of the public IP. If the public IP has never been associated before, then you won't have an ip address yet.
region string	The region where the public IP address is located.
sku string	The sku of the public IP. Possible values: BASIC, STANDARD.
domainName string	The subdomain part of the fqdn. This is only present if one is defined.
fqn string	The fqdn which points to the public IP.
idleTimeout integer	The number of minutes for the idleTimeout. It can be between 4 and 30 minutes.
allocationMethod string	Allocation method of the public IP address. Possible values: DYNAMIC, STATIC.
ipVersion string	IP version of the public IP address. Possible values: IPV4, IPV6.

Retrieve a public ip address

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/publicipaddresses/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip",
    "name": "some-public-ip",
    "state": "DETACHED",
    "ipAddress": "52.122.12.1",
    "region": "eastus",
    "domainName": "somepublicip",
    "fqdn": "somepublicip.eastus.cloudapp.azure.com",
    "sku": "BASIC",
    "idleTimeout": 7,
    "allocationMethod": "DYNAMIC",
    "ipVersion": "IPV4"
  }
}

GET /services/:service_code/:environment_name/publicipaddresses/:id

Retrieve a public IP address in a given environment.

Attributes
id string	The id of the public IP address. This is a canonized id from azure which is the form of /subscriptions/:subscriptionid/resourceGroups/:resourcegroup/providers/Microsoft.Network/publicIPAddresses/:publicIpName.
name string	The name of the public IP address.
state string	The state of the public IP address. Possible state: ATTACHED, DETACHED, UPDATING, DELETING.
ipAddress string	The IP address of the public IP. If the public IP has never been associated before, then you won't have an ip address yet.
region string	The region where the public IP address is located.
sku string	The sku of the public IP. Possible values: BASIC, STANDARD.
domainName string	The subdomain part of the fqdn. This is only present if one is defined.
fqn string	The fqdn which points to the public IP.
idleTimeout integer	The number of minutes for the idleTimeout. It can be between 4 and 30 minutes.
allocationMethod string	Allocation method of the public IP address. Possible values: DYNAMIC, STATIC.
ipVersion string	IP version of the public IP address. Possible values: IPV4, IPV6.

Create a public ip address

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body"
   "https://cloudmc_endpoint/api/v1/services/azure/example/publicipaddresses"

Request body example:

{
    "name":"samplePublicIP",
    "region" : "canadacentral",
    "sku": "BASIC",
    "allocationMethod" : "DYNAMIC",
    "idleTimeout" : 30,
    "domainName" : "samplePublicIP"
}

POST /services/:service_code/:environment_name/publicipaddresses

Create a public IP address in a given environment.

Required
name string	The name of the public IP address.
region string	The region where the public IP address is located.

Optional
sku string	The sku of the public IP. Possible values: BASIC, STANDARD. Default value is BASIC.
allocationMethod string	Allocation method of the public IP address. Possible values: DYNAMIC, STATIC. Default value is DYNAMIC for SKU BASIC, and STATIC for SKU STANDARD.
idleTimeout integer	The number of minutes for the idleTimeout. It can be between 4 and 30 minutes. Default value is 4 minutes.
domainName string	The subdomain part of the fqdn.

Associate a public ip address

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body"
   "https://cloudmc_endpoint/api/v1/services/azure/example/publicipaddresses?operation=associate"

Request body example:

{
    "networkInterfaceId": "subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/networkInterfaces/nic68108672c3b"
}

POST /services/:service_code/:environment_name/publicipaddresses?operation=associate

Associate a public IP address in a given environment to a network interface.

Required
networkInterfaceId string	Id of the network interface associated to an instance. Th network interface must be in the same region as the public IP address.

Delete a public IP address

curl -X DELETE \
  'http://cloudmc_endpoint/v1/services/azure/example/publicipaddresses/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip' \
  -H 'mc-api-key: your_api_key'

DELETE /services/:service_code/:environment_name/publicipaddresses/:id

Delete an existing public IP address.

Update a public ip address

curl -X PUT \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body"
   "https://cloudmc_endpoint/api/v1/services/azure/example/publicipaddresses//subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.Network/publicIPAddresses/some-public-ip"

Request body example:

{
    "allocationMethod" : "DYNAMIC",
    "idleTimeout" : 30,
    "domainName" : "samplePublicIP"
}

PUT /services/:service_code/:environment_name/publicipaddresses/:id

Update a public IP address in a given environment.

Attribute
allocationMethod string	Allocation method of the public IP address. Possible values: DYNAMIC, STATIC. Not providing it will keep the actual value. Cannot be change for Standard SKU public IP address.
idleTimeout integer	The number of minutes for the idleTimeout. It can be between 4 and 30 minutes. Not providing it will keep the actual value.
domainName string	The subdomain part of the fqdn. If it is empty or not provided, the entry will be removed from the DNS.

Kubernetes

Clusters

Deploy and manage your Azure Kubenetes Service (AKS) Clusters.

For information regarding AKS clusters, please see azure docs.

List AKS clusters

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/clusters"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "/subscriptions/9e548d49-7d56-452c-8fc8-e81a25d05ddf/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean",
      "name": "ssamadh-basic",
      "version": "premium_lrs",
      "region": "southeastasia",
      "nodePools": "4",
      "totalNodes": "7",
    },
    {
       "id": "/subscriptions/ 803c8d4a-80ca-4793-8def-89b5f55d1091/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean",
      "name": "ssamadh-basic",
      "version": "premium_lrs",
      "region": "southeastasia",
      "nodePools": "2",
      "totalNodes": "3",
    },
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/clusters

Retrieve a list of all the AKS clusters in a given environment.

Attributes
data array	A list of Azure Kubenetes Service (AKS) Clusters. (See "Retrieve an AKS cluster" API for the strucutre of each AKS cluster object)
metadata object	Consists of the meta information related to the returned cluster list. The attribute recordCount contains the number of clusters returned.

Retrieve an AKS clusters

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/clusters/subscriptions/9e548d49-7d56-452c-8fc8-e81a25d05ddf/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean"

Note: The above example uses the complete cluster id set by Azure. However, the cluster may also be retrieved by the cluster name as shown below:

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure-conn/test_env/clusters/ssamadh-aks-mean"

The above command returns a JSON structured like this:

{
  "data": {
      "id": "/subscriptions/9e548d49-7d56-452c-8fc8-e81a25d05ddf/resourcegroups/azure-connect-system-ssamadh-mean-env/providers/Microsoft.ContainerService/managedClusters/ssamadh-aks-mean",
      "name": "ssamadh-basic",
      "version": "premium_lrs",
      "region": "southeastasia",
      "nodePools": "4",
      "totalNodes": "7",
    },
}

GET /services/:service_code/:environment_name/clusters/:cluster_name

Retrieve a specific AKS cluster in a given environment.

Attributes
id string	The resource id
name string	The name of the resource, unique within the environment
provisioningState string	The state of the cluster could be any of [Succeeded, Creating, Deleting, Updating, Cancelled, Failed]
dnsPrefix string	The DNS prefix specified when creating the managed cluster
nodePools int	The number of node container service agent pool
totalNodes int	The total number of nodes across all nodePools
rbacEnabled boolean	Indicates of RBAC is enabled for this kubernetes cluster
endpoint string	The fully qualified domain name (fqdn) for the master pool
region string	The resource location
version string	The version of kubernetes running in the cluster

Create a cluster

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "http://cloudmc_endpoint/v1/services/azure/example/clusters"

Request body examples:

{
    "version": "1.18.2",
    "dnsPrefix": "kub-root-nik-dns",
    "rootUsername": "root_nzk",
    "primaryPoolNodeType": "Standard_B2ms",
    "primaryPoolNodeCount": 1,
    "vmScaleSetsEnabled": false,
    "rbacEnabled": false,
    "region": "canadacentral",
    "name": "kub_root_nzk",
    "sshkey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQCguvgDRuUF/wijOJCNmYlQHujCmUHl/i0Ubos4nHy5uCBdn1LGF+PG3TpJqO1LUWqpHaPl4yN7bpsdXyq6a9nxe0C1bQ4FK6P5qm0X320uvqv34jwTPsIbnhw9I317df+xJyXXsL/P5vS4ULPMC5UZjWm4BYe7did4zmXXhA/zmLY6cUg19sZp5r5SUQcf5xHAqO3cQVZwzBhBMwroflZZ59zNpxy+xXPBqC3IdusF2yTDW7bwCQHESUOsd9XhwrzCB+1wETKjLpk0wkWj8G2j1pkKGRpv60QcG85lbZvQAg54v3HYD7fVJCaz9gJJoiyRBnqQ6XVxam5bZgiMKa0J johndoe@machine.local"
}

POST /services/:service_code/:environment_name/clusters

Create a new cluster.

Required
dnsPrefix string	The DNS prefix to be used to create the FQDN for the master pool.
name string	. The name of the cluster.
primaryPoolNodeCount string	The number of agents (VMs) to host docker containers. Allowed values must be in the range of 1 to 100 (inclusive).
primaryPoolNodeType string	The size type of each virtual machine in the agent pool.
rbacEnabled boolean	A boolean to indicate whether RBAC should be enabled on this cluster or not.
region string	The name of the region for the cluster.
sshkey string	The ssh key public portion that will be used to access cluster.
version string	The version for the Kubernetes cluster.
vmScaleSetsEnabled boolean	The boolean to indicate whether to use virtual machine scale sets or availability set for agent pool.

Optional
rootUsername string	The user name to create a root user on cluster.

Delete a cluster

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/azure/example/clusters/subscriptions/subscriptionId/resourceGroups/cmc-example/providers/Microsoft.ContainerService/managedClusters/sample_small_cluster"

The above command returns a JSON structured like this:

{
  "taskId": "3e4d4466-ce4b-404b-ada5-ee5a3fb76f4e",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/clusters/:id

Delete an existing cluster.

Namespaces

List namespaces

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "default",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 4
  }
}

GET /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id

Retrieve a list of all namespaces in a given environment.

Required
cluster_id string	The id of the cluster in which to list the namespaces.

Attributes
id string	The id of the namespace.
apiVersion string	APIVersion defines the versioned schema of this representation of a namespace object
metadata object	The metadata of the namespace
spec object	The specification describes the attributes on a namespace.
status object	The status information of the namespace

Get a namespace

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces/cert-manager?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "default",
    "apiVersion": "v1",
    "kind": "Namespace",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id

Retrieve a namespace and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the namespace.

Attributes
id string	The id of the namespace.
apiVersion string	APIVersion defines the versioned schema of this representation of a namespace object
metadata object	The metadata of the namespace
spec object	The specification describes the attributes on a namespace.
status object	The status information of the namespace

Create a namespace

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces?cluster_id=test-cluster"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Namespace",
  "metadata": {
    "name": "test-namespace"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/namespaces?cluster_id=:cluster_id

Create a namespace in a given environment.

Required
cluster_id string	The id of the cluster in which to get the namespace.

Required Attributes
apiVersion string	The api version (versioned schema) of the namespace.
metadata object	The metadata of the namespace.
metadata.name string	The name of the namespace.

Return value:

Attributes
taskId string	The id corresponding to the create namespace task.
taskStatus string	The status of the operation.

Delete a namespace

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/namespaces/test-namespace?cluster_id=test-cluster"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/namespaces/:id?cluster_id=:cluster_id

Delete a namespace from a given environment.

Required
cluster_id string	The id of the cluster in which to get the namespace.

Attributes
taskId string	The id corresponding to the delete namespaces task.
taskStatus string	The status of the operation.

Workloads

Pods

List pods

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-aerospike-0/default",
      "metadata": {
        "annotations": {
          "checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
        },
        "creationTimestamp": "2020-01-20T09:35:02.000-05:00",
        "generateName": "my-aerospike-",
        "labels": {
          "app": "aerospike",
          "controller-revision-hash": "my-aerospike-d9969496d",
          "release": "my-aerospike",
          "statefulset.kubernetes.io/pod-name": "my-aerospike-0"
        },
        "name": "my-aerospike-0",
        "namespace": "default",
        "ownerReferences": [
          {
            "apiVersion": "apps/v1",
            "blockOwnerDeletion": true,
            "controller": true,
            "kind": "StatefulSet",
            "name": "my-aerospike",
            "uid": "0b00ea3d-3b92-11ea-935e-025000000001"
          }
        ],
        "resourceVersion": "95058",
        "selfLink": "/api/v1/namespaces/default/pods/my-aerospike-0",
        "uid": "0b055519-3b92-11ea-935e-025000000001"
      },
      "spec": {
        "containers": [
          {
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imagePullPolicy": "IfNotPresent",
            "name": "my-aerospike",
            "ports": [
              {
                "containerPort": 3000,
                "name": "clients",
                "protocol": "TCP"
              },
              {
                "containerPort": 3002,
                "name": "mesh",
                "protocol": "TCP"
              },
              {
                "containerPort": 3003,
                "name": "info",
                "protocol": "TCP"
              }
            ],
            "readinessProbe": {
              "failureThreshold": 3,
              "initialDelaySeconds": 15,
              "periodSeconds": 10,
              "successThreshold": 1,
              "tcpSocket": {
                "port": 3000
              },
              "timeoutSeconds": 1
            },
            "resources": {},
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "volumeMounts": [
              {
                "mountPath": "/etc/aerospike",
                "name": "config-volume"
              },
              {
                "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
                "name": "default-token-64jnc",
                "readOnly": true
              }
            ]
          }
        ],
        "dnsPolicy": "ClusterFirst",
        "enableServiceLinks": true,
        "hostname": "my-aerospike-0",
        "nodeName": "docker-desktop",
        "priority": 0,
        "restartPolicy": "Always",
        "schedulerName": "default-scheduler",
        "securityContext": {},
        "serviceAccount": "default",
        "serviceAccountName": "default",
        "subdomain": "my-aerospike",
        "terminationGracePeriodSeconds": 30,
        "tolerations": [
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/not-ready",
            "operator": "Exists",
            "tolerationSeconds": 300
          },
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/unreachable",
            "operator": "Exists",
            "tolerationSeconds": 300
          }
        ],
        "volumes": [
          {
            "configMap": {
              "defaultMode": 420,
              "items": [
                {
                  "key": "aerospike.conf",
                  "path": "aerospike.conf"
                }
              ],
              "name": "my-aerospike"
            },
            "name": "config-volume"
          },
          {
            "name": "default-token-64jnc",
            "secret": {
              "defaultMode": 420,
              "secretName": "default-token-64jnc"
            }
          }
        ]
      },
      "status": {
        "conditions": [
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "Initialized"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "Ready"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "ContainersReady"
          },
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "PodScheduled"
          }
        ],
        "containerStatuses": [
          {
            "containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
            "lastState": {
              "terminated": {
                "containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
                "exitCode": 255,
                "finishedAt": "2020-01-21T15:04:35.000-05:00",
                "reason": "Error",
                "startedAt": "2020-01-20T10:28:19.000-05:00"
              }
            },
            "name": "my-aerospike",
            "ready": true,
            "restartCount": 2,
            "state": {
              "running": {
                "startedAt": "2020-01-21T15:05:16.000-05:00"
              }
            }
          }
        ],
        "hostIP": "192.168.65.3",
        "phase": "Running",
        "podIP": "10.1.0.129",
        "qosClass": "BestEffort",
        "startTime": "2020-01-20T09:35:02.000-05:00"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/pods?cluster_id=:cluster_id

Retrieve a list of all pods in a given environment.

Required
cluster_id string	The id of the cluster in which to list the pods.

Attributes
id string	The id of the pod.
metadata object	The metadata of the pod.
metadata.annotations map	The annotations of the pod.
metadata.creationTimestamp string	The date of creation of the pod as a string.
metadata.labels map	The labels associated to the pod.
metadata.name string	The name of the pod.
metadata.namespace string	The namespace in which the pod is created.
metadata.uid object	The UUID of the pod.
spec object	The specification used to create and run the pod.
spec.container string	The name of the container running.
status object	The status information of the pod.
status.phase string	The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a pod

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "my-aerospike-0/default",
      "metadata": {
        "annotations": {
          "checksum/config": "0e07919467cc16f2c07ac99d0036405deafa06f7d3b430215915470b3a6ca631"
        },
        "creationTimestamp": "2020-01-20T09:35:02.000-05:00",
        "generateName": "my-aerospike-",
        "labels": {
          "app": "aerospike",
          "controller-revision-hash": "my-aerospike-d9969496d",
          "release": "my-aerospike",
          "statefulset.kubernetes.io/pod-name": "my-aerospike-0"
        },
        "name": "my-aerospike-0",
        "namespace": "default",
        "ownerReferences": [
          {
            "apiVersion": "apps/v1",
            "blockOwnerDeletion": true,
            "controller": true,
            "kind": "StatefulSet",
            "name": "my-aerospike",
            "uid": "0b00ea3d-3b92-11ea-935e-025000000001"
          }
        ],
        "resourceVersion": "95058",
        "selfLink": "/api/v1/namespaces/default/pods/my-aerospike-0",
        "uid": "0b055519-3b92-11ea-935e-025000000001"
      },
      "spec": {
        "containers": [
          {
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imagePullPolicy": "IfNotPresent",
            "name": "my-aerospike",
            "ports": [
              {
                "containerPort": 3000,
                "name": "clients",
                "protocol": "TCP"
              },
              {
                "containerPort": 3002,
                "name": "mesh",
                "protocol": "TCP"
              },
              {
                "containerPort": 3003,
                "name": "info",
                "protocol": "TCP"
              }
            ],
            "readinessProbe": {
              "failureThreshold": 3,
              "initialDelaySeconds": 15,
              "periodSeconds": 10,
              "successThreshold": 1,
              "tcpSocket": {
                "port": 3000
              },
              "timeoutSeconds": 1
            },
            "resources": {},
            "terminationMessagePath": "/dev/termination-log",
            "terminationMessagePolicy": "File",
            "volumeMounts": [
              {
                "mountPath": "/etc/aerospike",
                "name": "config-volume"
              },
              {
                "mountPath": "/var/run/secrets/kubernetes.io/serviceaccount",
                "name": "default-token-64jnc",
                "readOnly": true
              }
            ]
          }
        ],
        "dnsPolicy": "ClusterFirst",
        "enableServiceLinks": true,
        "hostname": "my-aerospike-0",
        "nodeName": "docker-desktop",
        "priority": 0,
        "restartPolicy": "Always",
        "schedulerName": "default-scheduler",
        "securityContext": {},
        "serviceAccount": "default",
        "serviceAccountName": "default",
        "subdomain": "my-aerospike",
        "terminationGracePeriodSeconds": 30,
        "tolerations": [
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/not-ready",
            "operator": "Exists",
            "tolerationSeconds": 300
          },
          {
            "effect": "NoExecute",
            "key": "node.kubernetes.io/unreachable",
            "operator": "Exists",
            "tolerationSeconds": 300
          }
        ],
        "volumes": [
          {
            "configMap": {
              "defaultMode": 420,
              "items": [
                {
                  "key": "aerospike.conf",
                  "path": "aerospike.conf"
                }
              ],
              "name": "my-aerospike"
            },
            "name": "config-volume"
          },
          {
            "name": "default-token-64jnc",
            "secret": {
              "defaultMode": 420,
              "secretName": "default-token-64jnc"
            }
          }
        ]
      },
      "status": {
        "conditions": [
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "Initialized"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "Ready"
          },
          {
            "lastTransitionTime": "2020-01-21T15:05:33.000-05:00",
            "status": "True",
            "type": "ContainersReady"
          },
          {
            "lastTransitionTime": "2020-01-20T09:35:02.000-05:00",
            "status": "True",
            "type": "PodScheduled"
          }
        ],
        "containerStatuses": [
          {
            "containerID": "docker://b45436d2978cb8e6186b22c24d3b819cabd00921a009b30c2599a935d0c69b49",
            "image": "aerospike/aerospike-server:4.5.0.5",
            "imageID": "docker-pullable://aerospike/aerospike-server@sha256:5bec98d46c8a521003e1c5b6f015713f2663384dd66916cca696e4e1c142c539",
            "lastState": {
              "terminated": {
                "containerID": "docker://5e4b23c07269669f302c7c6a446399e59d553cf1a622094c1d3cc64b6f65a9e0",
                "exitCode": 255,
                "finishedAt": "2020-01-21T15:04:35.000-05:00",
                "reason": "Error",
                "startedAt": "2020-01-20T10:28:19.000-05:00"
              }
            },
            "name": "my-aerospike",
            "ready": true,
            "restartCount": 2,
            "state": {
              "running": {
                "startedAt": "2020-01-21T15:05:16.000-05:00"
              }
            }
          }
        ],
        "hostIP": "192.168.65.3",
        "phase": "Running",
        "podIP": "10.1.0.129",
        "qosClass": "BestEffort",
        "startTime": "2020-01-20T09:35:02.000-05:00"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id

Retrieve a pod and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the pod.

Attributes
id string	The id of the pod.
metadata object	The metadata of the pod.
metadata.annotations map	The annotations of the pod.
metadata.creationTimestamp string	The date of creation of the pod as a string.
metadata.labels map	The labels associated to the pod.
metadata.name string	The name of the pod.
metadata.namespace string	The namespace in which the pod is created.
metadata.uid object	The UUID of the pod.
spec object	The specification used to create and run the pod.
spec.container string	The name of the container running.
status object	The status information of the pod.
status.phase string	The status of the pod. Possible statuses are Running, Pending, Succeeded, Unknown and Failed.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a pod

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods"
  Content-Type: application/json
  {
      "apiVersion": "v1",
    "kind": "Pod",
      "metadata": {
        "name": "edgar-allen-pod",
          "namespace": "default"
    },
      "spec": {
        "containers": [
            {
                "image": "nginx",
                "name": "nginx"
            }
          ]
      }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/pods

Create a pod in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the pod
metadata object	The metadata of the pod
metadata.name string	The name of the pod
spec object	The specification used to create and run the pod
spec.container.image string	The docker image name
spec.container.name string	The (unique) name of the container specified as a DNS_LABEL

Optional Attributes
metadata.namespace string	The namespace in which the pod is created

Return value:

Attributes
taskId string	The id corresponding to the create pod task.
taskStatus string	The status of the operation.

Replace a pod

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/edgar-allen-pod/default"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "kind": "Pod",
      "metadata": {
        "name": "edgar-allen-pod",
          "namespace": "default"
  },
      "spec": {
        "containers": [
            {
                "image": "nginx",
                "name": "nginx"
            }
          ]
      }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/pods/:id

Replace a pod in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the pod.
metadata object	The metadata of the pod.
metadata.name string	The name of the pod.
spec object	The specification used to replace and run the pod.
spec.container.image string	The docker image name.
spec.container.name string	The (unique) name of the container specified as a DNS_LABEL.

Optional Attributes
metadata.namespace string	The namespace in which the pod is replaced.

Return value:

Attributes
taskId string	The id corresponding to the replace pod task.
taskStatus string	The status of the operation.

Delete a pod

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/pods/my-aerospike-0/default?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/pods/:id?cluster_id=:cluster_id

Delete a pod from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the pod.

Attributes
taskId string	The task id related to the delete pod task.
taskStatus string	The status of the operation.

Deployments

List deployments

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "coredns/kube-system",
      "deploymentStatus": "Progressing",
      "readyRatio": "2/2",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 6
  }
}

GET /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id

Retrieve a list of all deployments in a given environment.

Required
cluster_id string	The id of the cluster in which to list the deployments.

Attributes
id string	The id of the deployment
metadata object	The metadata of the deployment
images object	The container images within a deployment
spec object	The specification used to create and run the deployment
readyRatio object	The ready replicas to total replicas ratio of this deployment set
deploymentStatus object	The status information of the deployment

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a deployment

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/coredns/kube-system?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "coredns/kube-system",
    "deploymentStatus": "Progressing",
    "readyRatio": "2/2",
    "apiVersion": "apps/v1",
    "kind": "Deployment",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id

Retrieve a deployment and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the deployment.

Attributes
id string	The id of the deployment
metadata object	The metadata of the deployment
images object	The container images within a deployment
spec object	The specification used to create and run the deployment
readyRatio object	The ready replicas to total replicas ratio of this deployment set
deploymentStatus object	The status information of the deployment

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a deployment

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "api-test-deployment-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "nginx"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/deployments?cluster_id=:cluster_id

Create a deployment in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the deployment.
metadata object	The metadata of the deployment.
metadata.name string	The name of the deployment.
spec object	The specification used to replace and run the deployment.
spec.selector object	The label query over the deployment's set of resources.
spec.template object	The data a deployment's pod should have when replaced.
spec.spec object	The specification used to replace and run the pod(s) within the deployment.

Optional Attributes
metadata.namespace string	The namespace in which the deployment is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a deployment.

Return value:

Attributes
taskId string	The id corresponding to the replace deployment task.
taskStatus string	The status of the operation.

Replace a deployment

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/deployment-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "Deployment",
  "metadata": {
    "name": "deployment-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "nginx"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/deployments/:id

Replace a deployment in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the deployment.
metadata object	The metadata of the deployment.
metadata.name string	The name of the deployment.
spec object	The specification used to create and run the deployment.
spec.selector object	The label query over the deployment's set of resources.
spec.template object	The data a deployment's pod should have when created.
spec.spec object	The specification used to create and run the pod(s) within the deployment.

Optional Attributes
metadata.namespace string	The namespace in which the deployment is created.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a deployment.

Return value:

Attributes
taskId string	The id corresponding to the create deployment task.
taskStatus string	The status of the operation.

Delete a deployment

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/deployments/dex/auth?cluster_id=a_cluster_id?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/deployments/:id?cluster_id=:cluster_id

Delete a deployment from a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to list the deployments.

Return value:

Attributes
taskId string	The id corresponding to the delete deployment task.
taskStatus string	The status of the operation.

Daemon Sets

List daemon sets

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "kube-proxy/kube-system",
      "readyRatio": "3/3",
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 5
  }
}

GET /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id

Retrieve a list of all daemon sets in a given environment.

Required
cluster_id string	The id of the cluster in which to list the daemon sets.

Attributes
id string	The id of the daemon set
metadata object	The metadata of the daemon set
spec object	The specification used to create and run the daemon set
status object	The status information of the daemon set

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a daemon set

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/test-aerospike/auth?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "kube-proxy/kube-system",
    "readyRatio": "3/3",
    "apiVersion": "apps/v1",
    "kind": "DaemonSet",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id

Retrieve a daemon set and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the daemon set.

Attributes
id string	The id of the daemon set
metadata object	The metadata of the daemon set
spec object	The specification used to create and run the daemon set
status object	The status information of the daemon set

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a daemon set

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "metadata": {
    "name": "daemonset-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "name": "fluentd-elasticsearch"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "fluentd-elasticsearch"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "fluentd-elasticsearch",
            "image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/daemonsets?cluster_id=:cluster_id

Create a daemon set in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to get the daemon set.
apiVersion string	The api version (versioned schema) of the daemon set
metadata object	The metadata of the daemon set
metadata.name string	The name of the daemon set
spec object	The specification used to create and run the daemon set
spec.selector object	The label query over the daemon set's resources
spec.template object	The data a daemon set's pod should have when created
spec.spec object	The specification used to create and run the pod(s) within the daemon set

Optional Attributes
metadata.namespace string	The namespace in which the daemon set is created
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a daemon set

Return value:

Attributes
taskId string	The id corresponding to the create daemon set task.
taskStatus string	The status of the operation.

Replace a daemon set

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/daemonset-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "DaemonSet",
  "metadata": {
    "name": "daemonset-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "name": "fluentd-elasticsearch"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "fluentd-elasticsearch"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "fluentd-elasticsearch",
            "image": "quay.io/fluentd_elasticsearch/fluentd:v2.5.2"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/daemonsets/:id

Replace a daemon set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the daemon set.
metadata object	The metadata of the daemon set.
metadata.name string	The name of the daemon set.
spec object	The specification used to replace and run the daemon set.
spec.selector object	The label query over the daemon set's resources.
spec.template object	The data a daemon set's pod should have when replaced.
spec.spec object	The specification used to create and run the pod(s) within the daemon set.

Optional Attributes
metadata.namespace string	The namespace in which the daemon set is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a daemon set.

Return value:

Attributes
taskId string	The id corresponding to the replace daemon set task.
taskStatus string	The status of the operation.

Delete a daemon set

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/daemonsets/nginx-ingress-controller/ingress-nginx?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/daemonsets/:id?cluster_id=:cluster_id

Delete a daemon set from a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to get the daemon set.

Return value:

Attributes
taskId string	The id corresponding to the delete daemon set task.
taskStatus string	The status of the operation.

Stateful Sets

List stateful sets

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "test-aerospike/auth",
      "images": ["aerospike/aerospike-server:4.5.0.5"],
      "metadata": {},
      "spec": {},
      "status": {}
    }
  ],
  "metadata": {
    "recordCount": 4
  }
}

GET /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id

Retrieve a list of all stateful sets in a given environment.

Required
cluster_id string	The id of the cluster in which to list the stateful sets.

Attributes
id string	The id of the stateful set
metadata object	The metadata of the stateful set
spec object	The specification used to create and run the stateful set
status object	The status information of the stateful set

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a stateful set

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/test-aerospike/auth?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "test-aerospike/auth",
    "replicaRatio": "1 / 1",
    "images": ["aerospike/aerospike-server:4.5.0.5"],
    "apiVersion": "apps/v1",
    "kind": "StatefulSet",
    "metadata": {},
    "spec": {},
    "status": {}
  }
}

GET /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id

Retrieve a stateful set and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the stateful set.

Attributes
id string	The id of the stateful set
metadata object	The metadata of the stateful set
spec object	The specification used to create and run the stateful set
status object	The status information of the stateful set

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a stateful set

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind":"StatefulSet",
  "metadata": {
    "name": "stateful-set-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "k8s.gcr.io/nginx-slim:0.8"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/statefulsets?cluster_id=:cluster_id

Create a stateful set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the stateful set
metadata object	The metadata of the stateful set
metadata.name string	The name of the stateful set
spec object	The specification used to create and run the stateful set
spec.selector object	The label query over the stateful set's resources
spec.template object	The data a stateful set's pod should have when created
spec.spec object	The specification used to create and run the pod(s) within the stateful set

Optional Attributes
metadata.namespace string	The namespace in which the stateful set is created
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a stateful set

Return value:

Attributes
taskId string	The id corresponding to the create stateful set task.
taskStatus string	The status of the operation.

Replace a stateful set

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/stateful-set-name/default"
  Content-Type: application/json
  {
  "apiVersion": "apps/v1",
  "kind": "StatefulSet",
  "metadata": {
    "name": "stateful-set-name",
    "namespace": "default"
  },
  "spec": {
    "selector": {
      "matchLabels": {
        "app": "nginx"
      }
    },
    "template": {
      "metadata": {
        "labels": {
          "app": "nginx"
        }
      },
      "spec": {
        "containers": [
          {
            "name": "nginx",
            "image": "k8s.gcr.io/nginx-slim:0.8"
          }
        ]
      }
    }
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/statefulsets/:id

Replace a stateful set in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the stateful set.
metadata object	The metadata of the stateful set.
metadata.name string	The name of the stateful set.
spec object	The specification used to replaced and run the stateful set.
spec.selector object	The label query over the stateful set's of resources.
spec.template object	The data a stateful set's pod should have when replaced.
spec.spec object	The specification used to replace and run the pod(s) within the stateful set.

Optional Attributes
metadata.namespace string	The namespace in which the stateful set is replaced.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a stateful set.

Return value:

Attributes
taskId string	The id corresponding to the replace stateful set task.
taskStatus string	The status of the operation.

Delete a stateful set

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/statefulsets/my-aerospike/default"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/statefulsets/:id?cluster_id=:cluster_id

Delete a stateful set from a given environment.

Attributes
taskId string	The id corresponding to the delete stateful set task.
taskStatus string	The status of the operation.

Networking (k8s)

Services

List services

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "alaintest-aerospike/default",
      "ports": ["3000/TCP", "3002/TCP"],
      "type": "ClusterIP",
      "metadata": {},
      "spec": {},
      "status": {
        "loadBalancer": {}
      }
    },
    {
      "id": "alertmanager-operated/monitoring",
      "ports": ["9093/TCP", "9094/TCP", "9094/UDP"],
      "type": "NodePort",
      "apiVersion": "v1",
      "kind": "Service",
      "metadata": {},
      "spec": {},
      "status": {
        "loadBalancer": {}
      }
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/services?cluster_id=:cluster_id

Retrieve a list of all services in a given environment. | Required |   | | -------------------------- | -------------------------------------------------- | | cluster_id
string | The id of the cluster in which to get the service. |

Attributes
id string	The id of the service
metadata object	The metadata of the service
metadata.name string	The name of the service
metadata.namespace string	The namespace in which the service is created
metadata.uid object	The UUID of the service
type object	The container images within a service
ports object	The list of ports that are exposed by this service
spec object	The attributes that a user creates on a service
spec.selector object	The keys and values corresponding to pod labels, used to determine where service traffic will be routed

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a service

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/test-aerospike/auth?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "test-aerospike/auth",
    "ports": ["3000/TCP", "3002/TCP"],
    "type": "ClusterIP",
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {},
    "spec": {},
    "status": {
      "loadBalancer": {}
    }
  }
}

GET /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Retrieve a service and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Attributes
id string	The id of the service
metadata object	The metadata of the service
metadata.name string	The name of the service
metadata.namespace string	The namespace in which the service is created
metadata.uid object	The UUID of the service
type object	The container images within a service
ports object	The list of ports that are exposed by this service
spec object	The attributes that a user creates on a service
spec.selector object	The keys and values corresponding to pod labels, used to determine where service traffic will be routed

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a service

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Service",
  "metadata": {
    "name": "service-name",
    "namespace": "default"
  },
  "spec": {
    "ports": [
      {
        "port": 3000,
        "protocol": "TCP"
      }
    ],
    "type": "ClusterIP"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Create a service in a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Required Attributes
apiVersion string	The api version (versioned schema) of the service.
metadata object	The metadata of the service.
metadata.name string	The name of the service.
spec object	The specification used to create and run the service.
spec.selector object	The label query over the service's set of resources.
spec.ports object	The list of ports that are exposed by this service.
spec.type object	The type of service (ClusterIP, NodePort, ExternalName or LoadBalancer)

Optional Attributes
metadata.namespace string	The namespace in which the service is created.
spec.selector.matchLabels object	The key value pairs retrieved by a label query from a service.

Return value:

Attributes
taskId string	The id corresponding to the create service task.
taskStatus string	The status of the operation.

Replace a service

curl -X PUT </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/service-name/default?cluster_id=test-cluster"

Request body example:

{
    "type": "LoadBalancer",
    "ports": [
        "4000/TCP"
    ],
    "apiVersion": "v1",
    "kind": "Service",
    "metadata": {
        "creationTimestamp": "2020-08-13T11:05:00.000-04:00",
        "name": "service-name",
        "namespace": "default",
        "resourceVersion": "170742452",
        "selfLink": "/api/v1/namespaces/default/services/service-name",
        "uid": "a84c8fea-f9d9-47ab-8e58-37059e9f18bd"
    },
    "spec": {
        "clusterIP": "10.245.44.45",
        "externalTrafficPolicy": "Cluster",
        "ports": [
            {
                "nodePort": 31167,
                "port": 3000,
                "protocol": "TCP",
                "targetPort": 306
            }
        ],
        "sessionAffinity": "ClientIP",
        "sessionAffinityConfig": {
            "clientIP": {
                "timeoutSeconds": 10555
            }
        },
        "type": "LoadBalancer"
    },
    "status": {
        "loadBalancer": {}
    }
}

PUT /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Replace a service in a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Required Attributes
apiVersion string	The api version (versioned schema) of the service.
metadata object	The metadata of the service.
metadata.name string	The name of the service.
spec object	The specification used to create and run the service.

Return value:

Attributes
taskId string	The id corresponding to the replace service task.
taskStatus string	The status of the operation.

Delete a service

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/services/test-service/default?cluster_id=test-cluster"

DELETE /services/:service_code/:environment_name/services/:id?cluster_id=:cluster_id

Delete a service from a given environment.

Required
cluster_id string	The id of the cluster in which to get the service.

Attributes
taskId string	The id corresponding to the delete service task.
taskStatus string	The status of the operation.

Ingresses

List ingresses

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "cloudmc/cmc-stg",
      "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
      "service": {
        "port": "8080",
        "name": "cloudmc"
      },
      "metadata": {
        "annotations": {},
        "creationTimestamp": "2019-07-11T10:00:18.000-04:00",
        "generation": 10,
        "name": "cloudmc",
        "namespace": "cmc-stg",
        "resourceVersion": "143213903",
        "selfLink": "/apis/extensions/v1beta1/namespaces/cmc-stg/ingresses/cloudmc",
        "uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
      },
      "spec": {
        "rules": [],
        "tls": []
      },
      "status": {
        "loadBalancer": {}
      }
    },
    {
      "id": "cm-acme-http-solver-75png/auth",
      "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
      "service": {
        "port": "8089",
        "name": "cm-acme-http-solver-2x5gv"
      },
      "metadata": {
        "annotations": {},
        "creationTimestamp": "2020-06-24T11:00:49.000-04:00",
        "generateName": "cm-acme-http-solver-",
        "generation": 1,
        "labels": {
          "acme.cert-manager.io/http-domain": "1965164889",
          "acme.cert-manager.io/http-token": "820448657",
          "acme.cert-manager.io/http01-solver": "true"
        },
        "name": "cm-acme-http-solver-75png",
        "namespace": "auth",
        "ownerReferences": [],
        "resourceVersion": "143213968",
        "selfLink": "/apis/extensions/v1beta1/namespaces/auth/ingresses/cm-acme-http-solver-75png",
        "uid": "48720f48-f2bc-45fc-95c5-60cae8ffe11e"
      },
      "spec": {
        "rules": []
      },
      "status": {
        "loadBalancer": {}
      }
    }
  ]
}

GET /services/:service_code/:environment_name/ingresses?cluster_id=:cluster_id

Retrieve a list of all ingresses in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Attributes
id string	The id of the ingress
endpoint string	The endpoint of the ingress
service object	The service associated with the ingress
service.port string	The port of the service associated with the ingress
service.name string	The name of the service associated with the ingress
metadata object	The metadata of the ingress
metadata.name string	The name of the ingress
metadata.namespace string	The namespace in which the ingress is created
metadata.labels object	The labels associated with the ingress
metadata.uid object	The UUID of the ingress
spec object	The attributes that a user specifies for an ingress

Note that the list is not complete, since it is refering to the kubernetes api details.

Get an ingress

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/cloudmc/cmc-stg?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cloudmc/cmc-stg",
    "endpoint": "http://cmc.cloudmc-staging-endpoint.com",
    "service": {
      "port": "8080",
      "name": "cloudmc"
    },
    "metadata": {
      "annotations": {},
      "creationTimestamp": "2019-07-11T10:00:18.000-04:00",
      "generation": 10,
      "name": "cloudmc",
      "namespace": "cmc-stg",
      "resourceVersion": "143213903",
      "selfLink": "/apis/extensions/v1beta1/namespaces/cmc-stg/ingresses/cloudmc",
      "uid": "376bc4c5-a3e4-11e9-b6bd-02006e76001e"
    },
    "spec": {
      "rules": [],
      "tls": []
    },
    "status": {
      "loadBalancer": {}
    }
  }
}

GET /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Retrieve an ingress and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Attributes
id string	The id of the ingress
endpoint string	The endpoint of the ingress
service object	The service associated with the ingress
service.port string	The port of the service associated with the ingress
service.name string	The name of the service associated with the ingress
metadata object	The metadata of the ingress
metadata.name string	The name of the ingress
metadata.namespace string	The namespace in which the ingress is created
metadata.labels object	The labels associated with the ingress
metadata.uid object	The UUID of the ingress
spec object	The attributes that a user specifies for an ingress

Note that the list is not complete, since it is refering to the kubernetes api details.

Create an ingress

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses"
  Content-Type: application/json
  {
  "apiVersion": "networking.k8s.io/v1beta1",
  "kind": "Ingress",
  "metadata": {
    "name": "ingress-name",
    "namespace": "default",
    "annotations": {
      "nginx.ingress.kubernetes.io/rewrite-target": "/"
    }
  },
  "spec": {
    "rules": [
      {
        "hostname": "endpoint.com",
        "http": {
          "paths": [
            {
              "path": "/testpath",
              "pathType": "Prefix",
              "backend": {
                "serviceName": "test",
                "servicePort": 80
              }
            }
          ]
        }
      }
    ]
  }
}

POST /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Create an ingress in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Required Attributes
apiVersion string	The api version (versioned schema) of the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
spec object	The specification used to create and run the ingress.
spec.rules object	The list of host rules used to configure the ingress.

Optional Attributes
metadata.namespace string	The namespace in which the ingress is created.

Return value:

Attributes
taskId string	The id corresponding to the create ingress task.
taskStatus string	The status of the operation.

Replace an ingress

curl -X PUT </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/ingress-name/default?cluster_id=test-cluster"

Request body example:

{
  "endpoint": "http://my-endpoint.com",
  "service": {
    "port": "6556",
    "name": "test"
  },
  "apiVersion": "extensions/v1beta1",
  "kind": "Ingress",
  "metadata": {
    "creationTimestamp": "2020-08-13T14:13:42.000-04:00",
    "generation": 3,
    "name": "ingress-name",
    "namespace": "default",
    "resourceVersion": "170302224",
    "selfLink": "/apis/extensions/v1beta1/namespaces/default/ingresses/ingress-name",
    "uid": "c67e6a6a-2b07-4976-8b3d-2ec9fd91ae5d"
  },
  "spec": {
    "rules": [
      {
        "host": "my-endpoint.com",
        "http": {
          "paths": [
            {
              "backend": {
                "serviceName": "test",
                "servicePort": 6556
              },
              "path": "/testpath"
            }
          ]
        }
      }
    ]
  },
  "status": {
    "loadBalancer": {
      "ingress": [
        {
          "hostname": "hostname-worker-01"
        },
        {
          "hostname": "hostname-worker-02"
        },
        {
          "hostname": "hostname-worker-03"
        },
        {
          "hostname": "hostname-worker-04"
        }
      ]
    }
  }
}

PUT /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Replace an ingress in a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Required Attributes
apiVersion string	The api version (versioned schema) of the ingress.
metadata object	The metadata of the ingress.
metadata.name string	The name of the ingress.
spec object	The specification used to create and run the ingress.

Return value:

Attributes
taskId string	The id corresponding to the replace ingress task.
taskStatus string	The status of the operation.

Delete an ingress

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/ingresses/test-ingress/default?cluster_id=test-cluster"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/ingresses/:id?cluster_id=:cluster_id

Delete an ingress from a given environment.

Required
cluster_id string	The id of the cluster in which to get the ingress.

Return value:

Attributes
taskId string	The id corresponding to the delete ingress task.
taskStatus string	The status of the operation.

Configuration

Config Maps

List config maps

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "coredns/kube-system",
      "data": {
        "Corefile": ".:53 {\n    errors\n    health\n    kubernetes cluster.local in-addr.arpa ip6.arpa {\n      pods insecure\n      upstream\n      fallthrough in-addr.arpa ip6.arpa\n    }\n    prometheus :9153\n    forward . /etc/resolv.conf\n    cache 30\n    loop\n    reload\n    loadbalance\n    import custom/.override\n}\nimport custom/.server\n"
      },
      "metadata": {}
    }
  ],
  "metadata": {
    "recordCount": 4
  }
}

GET /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id

Retrieve a list of all config maps in a given environment.

Required
cluster_id string	The id of the cluster in which to list the config maps.

Attributes
id string	The id of the config map.
apiVersion string	The API version used to retrieve this config map.
metadata object	The metadata of the config map.

Get a config map

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/coredns/kube-system?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "coredns/kube-system",
    "apiVersion": "v1",
    "data": {
      "Corefile": ".:53 {\n    errors\n    health\n    kubernetes cluster.local in-addr.arpa ip6.arpa {\n      pods insecure\n      upstream\n      fallthrough in-addr.arpa ip6.arpa\n    }\n    prometheus :9153\n    forward . /etc/resolv.conf\n    cache 30\n    loop\n    reload\n    loadbalance\n    import custom/.override\n}\nimport custom/.server\n"
    },
    "kind": "ConfigMap",
    "metadata": {}
  }
}

GET /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id

Retrieve a config map and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the config map.

Attributes
id string	The id of the config map.
apiVersion string	The API version used to retrieve this config map.
metadata object	The metadata of the config map.

Create a config map

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "game-demo"
  },
  "data": {
    "player_initial_lives": "3",
    "ui_properties_file_name": "user-interface.properties",
    "game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
    "user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/configmaps?cluster_id=:cluster_id

Create a config map in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to create the config map.
apiVersion string	The api version (versioned schema) of the config map.
metadata object	The metadata of the config map.
metadata.name string	The name of the config map.
data object	The non-confidential data (in key-value pairs) stored in the config map.

Optional Attributes
metadata.namespace string	The namespace in which the config map is created

Return value:

Attributes
taskId string	The id corresponding to the create config maps task.
taskStatus string	The status of the operation.

Replace a config map

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/game-demo/default?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "ConfigMap",
  "metadata": {
    "name": "game-demo",
    "namespace": "default"
  },
  "data": {
    "player_initial_lives": "5",
    "ui_properties_file_name": "user-interface.properties",
    "game.properties": "enemy.types=aliens,monsters\nplayer.maximum-lives=5\n",
    "user-interface.properties": "color.good=purple\ncolor.bad=yellow\nallow.textmode=true\n"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id

Replace a config map in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to replace the config map.
apiVersion string	The api version (versioned schema) of the config map.
metadata object	The metadata of the config map.
metadata.name string	The name of the config map.
data object	The non-confidential data (in key-value pairs) stored in the config map.

Optional Attributes
metadata.namespace string	The namespace in which the config map is replaced.

Return value:

Attributes
taskId string	The id corresponding to the replace config maps task.
taskStatus string	The status of the operation.

Delete a config map

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/configmaps/cert-manager-cainjector-leader-election/kube-system?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/configmaps/:id?cluster_id=:cluster_id

Delete a config map from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the config map.

Attributes
taskId string	The id corresponding to the delete config map task.
taskStatus string	The status of the operation.

Secrets

List secrets

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "default-token-xxxmt/default",
      "apiVersion": "v1",
      "encodedData": {
        "ca.crt": "LS0tLS...",
        "namespace": "a3ViZS1zeXN0ZW0=",
        "token": "ZXlKa..."
      },
      "kind": "Secret",
      "metadata": {},
      "type": "kubernetes.io/service-account-token"
    }
  ],
  "metadata": {
    "recordCount": 100
  }
}

GET /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id

Retrieve a list of all secrets in a given environment.

Required
cluster_id string	The id of the cluster in which to list the secrets.

Attributes
id string	The id of the secret.
apiVersion string	The API version used to retrieve the secret.
encodedData object	The base64 encoded data stored in the secret.
metadata object	The metadata of the secret.
type string	A string used to facilitate programmatic handling of a secret's data.

Get a secret

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "default-token-xxxmt/default",
    "apiVersion": "v1",
    "encodedData": {
      "ca.crt": "LS0tLS...",
      "namespace": "a3ViZS1zeXN0ZW0=",
      "token": "ZXlKa..."
    },
    "kind": "Secret",
    "metadata": {},
    "type": "kubernetes.io/service-account-token"
  }
}

GET /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id

Retrieve a secret and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the secret.

Attributes
id string	The id of the secret.
apiVersion string	The API version used to retrieve the secret.
encodedData object	The base64 encoded data stored in the secret.
metadata object	The metadata of the secret.
type string	A string used to facilitate programmatic handling of a secret's data.

Create a secret

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "stringData": {
    "username": "my-username",
    "password": "my-password"
  }
}


# OR

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "encodedData": {
    "username": "YWRtaW4=",
    "password": "MWYyZDFlMmU2N2Rm"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/secrets?cluster_id=:cluster_id

Create a secret in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to create the secret.
apiVersion string	The api version (versioned schema) of the secret.
metadata object	The metadata of the secret.
metadata.name string	The name of the secret.

One of the following two attributes is also required.

Attributes
encodedData object	The base64 encoded data stored in the secret.
stringData object	The non-base64 encoded data to be encoded when the secret is created.

Optional Attributes
metadata.namespace string	The namespace in which the secret is created

Return value:

Attributes
taskId string	The id corresponding to the create secret task.
taskStatus string	The status of the operation.

Replace a secret

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/my-secret/shhh"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret"
  },
  "type": "Opaque",
  "stringData": {
    "username": "my-username",
    "password": "my-new-password"
  }
}


# OR

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets?cluster_id=:cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "v1",
  "kind": "Secret",
  "metadata": {
    "name": "mysecret",
    "namespace": "shhh"
  },
  "type": "Opaque",
  "encodedData": {
    "username": "YWRtaW4=",
    "password": "MWYyFZDlMmU2N2Rm"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id

Replace a secret in a given environment.

Required Attributes
cluster_id string	The id of the cluster in which to replace the secret.
apiVersion string	The api version (versioned schema) of the secret.
metadata object	The metadata of the secret.
metadata.name string	The name of the secret.

One of the following two attributes is also required.

Attributes
encodedData object	The base64 encoded data stored in the secret.
stringData object	The non-base64 encoded data to be encoded when the secret is replaced.

Optional Attributes
metadata.namespace string	The namespace in which the secret is replaced

Return value:

Attributes
taskId string	The id corresponding to the replace secret task.
taskStatus string	The status of the operation.

Delete a secret

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/secrets/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/secrets/:id?cluster_id=:cluster_id

Delete a secret from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the secret.

Attributes
taskId string	The id corresponding to the delete secret task.
taskStatus string	The status of the operation.

Storage (k8s)

Storage Classes

List storage classes

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "rook-ceph-block",
      "isDefault": true,
      "allowVolumeExpansion": true,
      "metadata": {
        "annotations": {
          "storageclass.kubernetes.io/is-default-class": "true"
        },
        "creationTimestamp": "2020-04-20T16:08:54.000-04:00",
        "name": "rook-ceph-block",
        "resourceVersion": "107033002",
        "selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
        "uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
      },
      "parameters": {
        "clusterID": "rook-ceph",
        "csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
        "csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
        "csi.storage.k8s.io/fstype": "ext4",
        "csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
        "csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
        "csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
        "csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
        "imageFeatures": "layering",
        "imageFormat": "2",
        "pool": "replicapool"
      },
      "provisioner": "rook-ceph.rbd.csi.ceph.com",
      "reclaimPolicy": "Delete",
      "volumeBindingMode": "Immediate"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id

Retrieve a list of all storage classes in a given environment.

Required
cluster_id string	The id of the cluster in which to list the storage classes.

Attributes
id string	The id of the storage class. This is the name of the resource.
isDefault boolean	Whether or not the storage class is the default one.
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.
metadata object	The metadata of the storage class.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
provisioner string	The provisioner for the storage class.
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Get a storage class

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "rook-ceph-block",
    "isDefault": true,
    "allowVolumeExpansion": true,
    "metadata": {
      "annotations": {
        "storageclass.kubernetes.io/is-default-class": "true"
      },
      "creationTimestamp": "2020-04-20T16:08:54.000-04:00",
      "name": "rook-ceph-block",
      "resourceVersion": "107033002",
      "selfLink": "/apis/storage.k8s.io/v1/storageclasses/rook-ceph-block",
      "uid": "f289c0e6-3f20-4274-8cb8-5db8b34dece6"
    },
    "parameters": {
      "clusterID": "rook-ceph",
      "csi.storage.k8s.io/controller-expand-secret-name": "rook-csi-rbd-provisioner",
      "csi.storage.k8s.io/controller-expand-secret-namespace": "rook-ceph",
      "csi.storage.k8s.io/fstype": "ext4",
      "csi.storage.k8s.io/node-stage-secret-name": "rook-csi-rbd-node",
      "csi.storage.k8s.io/node-stage-secret-namespace": "rook-ceph",
      "csi.storage.k8s.io/provisioner-secret-name": "rook-csi-rbd-provisioner",
      "csi.storage.k8s.io/provisioner-secret-namespace": "rook-ceph",
      "imageFeatures": "layering",
      "imageFormat": "2",
      "pool": "replicapool"
    },
    "provisioner": "rook-ceph.rbd.csi.ceph.com",
    "reclaimPolicy": "Delete",
    "volumeBindingMode": "Immediate"
  }
}

GET /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id

Retrieve a storage class and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to list the storage classes.

Attributes
id string	The id of the storage class. This is the name of the resource
isDefault boolean	Whether or not the storage class is the default one
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.
metadata object	The metadata of the storage class.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
provisioner string	The provisioner for the storage class
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Create a storage class

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
  "apiVersion": "storage.k8s.io/v1",
  "kind": "StorageClass",
  "metadata": {
    "name": "local-storage-name"
  },
  "provisioner": "kubernetes.io/no-provisioner",
  "volumeBindingMode": "WaitForFirstConsumer"
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/storageclasses?cluster_id=:cluster_id

Create a storage class in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the storage class.
metadata object	The metadata of the storage class.
metadata.name string	The name of the storage class.
provisioner string	The provisioner for the storage class
volumeBindingMode string	The default volume binding model for this storage class. You have a choice between Immediate or WaitForFirstConsumer.

Optional Attributes
reclaimPolicy string	The default volume reclaim policy for this storage class. You have a choice between Reclaim or Delete.
parameters object	The parameters for the storage provisioner. These are storage provisioner specific and you will likely have to read external documentation.
allowVolumeExpansion boolean	Whether not the storage class allows for expandable volumes.

Return value:

Attributes
taskId string	The id corresponding to the create stateful set task.
taskStatus string	The status of the operation.

Replace a storage class

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
    "apiVersion": "storage.k8s.io/v1",
    "metadata": {
        "name": "hostpath"
    },
    "provisioner": "docker.io/hostpath"
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id

Replace a storage class in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the storage class.
metadata object	The metadata of the storage class.
metadata.name string	The name of the storage class.
provisioner object	The type of provisioner.

Optional Attributes
reclaimPolicy string	Dynamically provisioned PersistentVolumes of this storage class are created with this reclaimPolicy. Defaults to Delete.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace storage class task.
taskStatus string	The status of the operation.

Delete a storage class

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/storageclasses/rook-ceph-block?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/storageclasses/:id?cluster_id=:cluster_id

Delete a storage class from a given environment.

Required
cluster_id string	The id of the cluster in which to get the storage class.

Attributes
taskId string	The id corresponding to the delete storage class task.
taskStatus string	The status of the operation.

Persistent volumes

List persistent volumes

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
      "metadata": {
        "annotations": {
          "pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
        },
        "creationTimestamp": "2020-07-03T09:12:17.000-04:00",
        "finalizers": ["kubernetes.io/pv-protection"],
        "name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
        "resourceVersion": "147569183",
        "selfLink": "/api/v1/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
        "uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
      },
      "spec": {
        "accessModes": ["ReadWriteOnce"],
        "capacity": {
          "storage": "8Gi"
        },
        "claimRef": {
          "apiVersion": "v1",
          "kind": "PersistentVolumeClaim",
          "name": "data-cmc-cluster-zookeeper-1",
          "namespace": "cmc-kafka",
          "resourceVersion": "147569124",
          "uid": "05097a93-120d-45d2-aaab-0f273849fccd"
        },
        "csi": {
          "driver": "rook-ceph.rbd.csi.ceph.com",
          "fsType": "ext4",
          "nodeStageSecretRef": {
            "name": "rook-csi-rbd-node",
            "namespace": "rook-ceph"
          },
          "volumeAttributes": {
            "clusterID": "rook-ceph",
            "imageFeatures": "layering",
            "imageFormat": "2",
            "pool": "replicapool",
            "storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
          },
          "volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
        },
        "persistentVolumeReclaimPolicy": "Delete",
        "storageClassName": "rook-ceph-block",
        "volumeMode": "Filesystem"
      },
      "status": {
        "phase": "Bound"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/persistentvolumes?cluster_id=:cluster_id

Retrieve a list of all persistent volumes in a given environment.

Required
cluster_id string	The id of the cluster in which to list the persistent volumes.

Attributes
id string	The id of the persistent volume. This is the name of the resource.
metadata object	The metadata of the persistent volume.
spec object	The specification of the persistent volume.
spec.accessModes string	The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.capacity.storage string	Storage capacity of the persistent volume.
spec.persistentVolumeReclaimPolicy string	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Get a persistent volume

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "id": "pvc-05097a93-120d-45d2",
  "metadata": {
    "annotations": {
      "pv.kubernetes.io/provisioned-by": "rook-ceph.rbd.csi.ceph.com"
    },
    "creationTimestamp": "2020-07-03T09:12:17.000-04:00",
    "finalizers": ["kubernetes.io/pv-protection"],
    "name": "pvc-05097a93-120d-45d2-aaab-0f273849fccd",
    "resourceVersion": "147569183",
    "selfLink": "/api/v1/persistentvolumes/pvc-05097a93-120d-45d2-aaab-0f273849fccd",
    "uid": "2e20a8fb-d90c-4c39-acd8-7007f85e2d8e"
  },
  "spec": {
    "accessModes": ["ReadWriteOnce"],
    "capacity": {
      "storage": "8Gi"
    },
    "claimRef": {
      "apiVersion": "v1",
      "kind": "PersistentVolumeClaim",
      "name": "data-cmc-cluster-zookeeper-1",
      "namespace": "cmc-kafka",
      "resourceVersion": "147569124",
      "uid": "05097a93-120d-45d2-aaab-0f273849fccd"
    },
    "csi": {
      "driver": "rook-ceph.rbd.csi.ceph.com",
      "fsType": "ext4",
      "nodeStageSecretRef": {
        "name": "rook-csi-rbd-node",
        "namespace": "rook-ceph"
      },
      "volumeAttributes": {
        "clusterID": "rook-ceph",
        "imageFeatures": "layering",
        "imageFormat": "2",
        "pool": "replicapool",
        "storage.kubernetes.io/csiProvisionerIdentity": "1593101040137-8081-rook-ceph.rbd.csi.ceph.com"
      },
      "volumeHandle": "0001-0009-rook-ceph-0000000000000001-d11d2a4d-bd2e-11ea-b56e-7a7db811cab1"
    },
    "persistentVolumeReclaimPolicy": "Delete",
    "storageClassName": "rook-ceph-block",
    "volumeMode": "Filesystem"
  },
  "status": {
    "phase": "Bound"
  }
}

GET /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id

Retrieve a persistent volume and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the persistent volume.

Attributes
id string	The id of the persistent volume. This is the name of the resource.
metadata object	The metadata of the persistent volume.
spec object	The specification of the persistent volume.
spec.accessModes string	The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.capacity.storage string	Storage capacity of the persistent volume.
spec.persistentVolumeReclaimPolicy string	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Create a persistent volume

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes"
  Content-Type: application/json
   {
      "apiVersion": "v1",
      "metadata": {
         "name": "small-pvc",
         "namespace": "default"
      },
      "spec": {
         "accessModes": [
            "ReadWriteOnce"
         ],
         "resources": {
            "requests": {
               "storage": "10G"
            }
         }
      }
   }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/persistentvolumes

Create a persistent volume in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the persistent volume.
metadata object	The metadata of the persistent volume.
metadata.name string	The name of the persistent volume.
spec object	The spec for the persistent volume.
spec.accessModes array	A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany.
spec.capacity.storage string	Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.
spec.<VOLUME_TYPE> object	Volume types are identified by name and what volume types are supported differ heavily by Kubernetes deployment. The contents of the object also depend on the volume type. Examples of common volumes types are nfs, hostPath, or local.

Optional Attributes
metadata.namespace string	The namespace in which the pod is created, if not specified will create the persistent volume in default.
spec.storageClassName string	Storage class associated to the volume.
spec.claimRef array	The name of the PersistentVolumeClaim associated to the persistent volume.
spec.mountOptions array	Mount options for when a Persistent Volume is mounted on a node.
spec.nodeAffinity array	Defines constraints that limit what nodes this volume can be accessed from.
spec.persistentVolumeReclaimPolicy array	One of Retain (manual reclamation), Recycle (basic scrub) or Delete (associated storage asset such as AWS EBS, GCE PD, Azure Disk, or OpenStack Cinder volume is deleted).
spec.volumeMode array	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status.phase string	Volume is in one of the following phases: Available, Bound, Released or Failed.

Return value:

Attributes
taskId string	The id corresponding to the create persistent volume task.
taskStatus string	The status of the operation.

Replace a persistent volume

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/my-persistent-volume?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "kind": "PersistentVolume",
    "metadata": {
        "annotations": {
            "key": "value"
        },
        "name": "persistentvolumes-name"
    },
    "spec": {
        "accessModes": [
            "ReadWriteMany"
        ],
        "capacity": {
            "storage": "2Gi"
        },
        "claimRef": {
            "apiVersion": "v1",
            "kind": "PersistentVolumeClaim",
            "name": "pv-claim-name",
            "namespace": "default",
            "resourceVersion": "259087",
            "uid": "11957feb-1acc-4c7e-911e-f77d5d7be5ac"
        },
        "hostPath": {
            "path": "/etc/path"
        },
        "persistentVolumeReclaimPolicy": "Retain",
        "storageClassName": "standard",
        "volumeMode": "Filesystem"
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=a_cluster_id

Replace a persistent volume in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the volume.
metadata object	The metadata of the volume.
metadata.name string	The name of the volume.
spec object	The specification used to replace and run the volume.
spec.accessModes string	The desired access modes the volume should have.
spec.capacity.storage string	The size of the claim.
spec.hostPath.path string	The path of the directory on the host.

Optional Attributes
metadata.annotations string	Annotations is an unstructured key value map stored with a resource that may be set by external tools to store and retrieve arbitrary metadata.
spec.claimRef string	part of a bi-directional binding between PersistentVolume and PersistentVolumeClaim. Expected to be non-nil when bound.
spec.persistentVolumeReclaimPolicy string	What happens to a persistent volume when released from its claim.
spec.storageClassName string	Name of StorageClass to which this persistent volume belongs. Empty value means that this volume does not belong to any StorageClass.
spec.volumeMode string	Defines if a volume is intended to be used with a formatted filesystem or to remain in raw block state. Value of Filesystem is implied when not included in spec.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace volume task.
taskStatus string	The status of the operation.

Delete a persistent volume

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumes/pvc-05097a93-120d-45d2?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/persistentvolumes/:id?cluster_id=:cluster_id

Delete a perstent volume from a given environment.

Required
cluster_id string	The id of the cluster in which to get the perstent volume.

Attributes
taskId string	The id corresponding to the delete persistent volume task.
taskStatus string	The status of the operation.

Persistent Volume Claims

List persistent volume claims

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "cmc-staging-mysql/cmc-stg",
      "metadata": {
        "annotations": {
          "pv.kubernetes.io/bind-completed": "yes",
          "pv.kubernetes.io/bound-by-controller": "yes",
          "volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
        },
        "creationTimestamp": "2020-04-27T12:01:22.000-04:00",
        "finalizers": ["kubernetes.io/pvc-protection"],
        "labels": {
          "app": "cmc-staging-mysql",
          "chart": "mysql-0.4.5",
          "heritage": "Helm",
          "release": "cmc-staging"
        },
        "name": "cmc-staging-mysql",
        "namespace": "cmc-stg",
        "resourceVersion": "111495311",
        "selfLink": "/api/v1/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
        "uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
      },
      "spec": {
        "accessModes": ["ReadWriteOnce"],
        "resources": {
          "requests": {
            "storage": "8Gi"
          }
        },
        "storageClassName": "rook-ceph-block",
        "volumeMode": "Filesystem",
        "volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
      },
      "status": {
        "accessModes": ["ReadWriteOnce"],
        "capacity": {
          "storage": "8Gi"
        },
        "phase": "Bound"
      }
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id

Retrieve a list of all persistent volume claims in a given environment.

Required
cluster_id string	The id of the cluster in which to list the persistent volume claims.

Attributes
id string	The id of the persistent volume claim. This is the name and namespace of the resource.
metadata object	The metadata of the persistent volume claim.
spec object	The specification of the persistent volume claim.
spec.accessModes string	The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.resources.requests.storage string	The requested storage capacity of the persistent volume.
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status object	The status of the persistent volume claim.
status.phase string	The claim is in one of the following phases: Pending, Bound, Lost or Terminating.
status.accessModes string	The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
status.capacity.storage string	The allocated storage capacity.

Get a persistent volume claim

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "cmc-staging-mysql/cmc-stg",
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
      "annotations": {
        "pv.kubernetes.io/bind-completed": "yes",
        "pv.kubernetes.io/bound-by-controller": "yes",
        "volume.beta.kubernetes.io/storage-provisioner": "rook-ceph.rbd.csi.ceph.com"
      },
      "creationTimestamp": "2020-04-27T12:01:22.000-04:00",
      "finalizers": ["kubernetes.io/pvc-protection"],
      "labels": {
        "app": "cmc-staging-mysql",
        "chart": "mysql-0.4.5",
        "heritage": "Helm",
        "release": "cmc-staging"
      },
      "name": "cmc-staging-mysql",
      "namespace": "cmc-stg",
      "resourceVersion": "111495311",
      "selfLink": "/api/v1/namespaces/cmc-stg/persistentvolumeclaims/cmc-staging-mysql",
      "uid": "ba115a65-e3c5-4e37-8548-e37ec395e79f"
    },
    "spec": {
      "accessModes": ["ReadWriteOnce"],
      "resources": {
        "requests": {
          "storage": "8Gi"
        }
      },
      "storageClassName": "rook-ceph-block",
      "volumeMode": "Filesystem",
      "volumeName": "pvc-ba115a65-e3c5-4e37-8548-e37ec395e79f"
    },
    "status": {
      "accessModes": ["ReadWriteOnce"],
      "capacity": {
        "storage": "8Gi"
      },
      "phase": "Bound"
    }
  }
}

GET /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id

Retrieve a persistent volume claim and all its info in a given environment.

Required
cluster_id string	The id of the cluster in which to get the persistent volume claim.

Attributes
id string	The id of the persistent volume claim. This is the name and namespace of the resource.
metadata object	The metadata of the persistent volume claim.
spec object	The specification of the persistent volume claim.
spec.accessModes string	The requested access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
spec.resources.requests.storage string	The requested storage capacity of the persistent volume.
spec.storageClassName string	Storage class associated to the volume.
spec.capacity.volumeMode string	If set to Filesystem (default value), the volume is mounted into Pods into a directory. If set to Block, then the volume is used as a raw block device.
status object	The status of the persistent volume claim.
status.phase string	The claim is in one of the following phases: Pending, Bound, Lost or Terminating.
status.accessModes string	The allocated access mode. The volume can be mounted on a host in any way supported by the resource provider and will give the provider access to different capabilities. Value is one of ReadWriteOnce (by a single node), ReadOnlyMany (by many nodes) or ReadWriteMany (by many nodes).
status.capacity.storage string	The allocated storage capacity.

Create a persistent volume claim

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims?cluster_id=a_cluster_id"
  Content-Type: application/json
{
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
        "name": "small-pvc",
        "namespace": "default"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "resources": {
            "requests": {
                "storage": "10G"
            }
        }
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/persistentvolumeclaims?cluster_id=:cluster_id

Create a persistent volume claim in a given environment.

Required
cluster_id string	The id of the cluster in which to list the persistent volume claims.

Required Attributes
apiVersion string	The api version (versioned schema) of the persistent volume claim.
metadata object	The metadata of the persistent volume claim.
metadata.name string	The name of the persistent volume claim.
spec object	The spec for the persistent volume claim.
spec.accessModes array	A list of access modes, the options are: ReadWriteOnce, ReadOnlyMany and ReadWriteMany.
spec.resources.requests.storage string	Measured in bytes. You can express storage as a plain integer or as a fixed-point integer using one of these suffixes: E, P, T, G, M, K. You can also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki.

Optional Attributes
metadata.namespace string	The namespace in which the pod is created, if not specified will create the claim in default.
spec.storageClassName string	The storage class for the persistent volume claim, will use the default if not specified.
spec.resources.limits object	Limits describe the maximum number of storage resources allowed.

Return value:

Attributes
taskId string	The id corresponding to the create persistent volume claim task.
taskStatus string	The status of the operation.

Replace a persistent volume claim

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/my-persistent-volume-claim/default?cluster_id=a_cluster_id"
  Content-Type: application/json
  {
    "id": "pv-claim-name/default",
    "apiVersion": "v1",
    "kind": "PersistentVolumeClaim",
    "metadata": {
        "name": "pv-claim-name",
        "namespace": "default"
    },
    "spec": {
        "accessModes": [
            "ReadWriteOnce"
        ],
        "resources": {
            "requests": {
                "storage": "1Gi"
            }
        },
        "storageClassName": "standard",
        "volumeName": "persistentvolumes-name",
        "dataSource": "dataSource"
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id

Replace a persistent volume claim in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the claim.
metadata object	The metadata of the claim.
metadata.name string	The name of the claim.
spec object	The specification used to replace and run the claim.
spec.accessModes string	The desired access modes the volume should have.
spec.resources.requests.storage string	The size of the claim.
spec.storageClassName string	The name of the StorageClass required by the claim.

Optional Attributes
spec.volumeName string	The binding reference to the PersistentVolume backing this claim. Only required if claim is bound.
spec.volumemode string	What type of volume is required by the claim. Value of Filesystem is implied when not included in claim spec.
spec.dataSource string	This field can be used to specify either: an existing VolumeSnapshot object, an existing PVC or an existing custom resource/object that implements data population.

Note that the list is not complete, since it is refering to the kubernetes api details.

Return value:

Attributes
taskId string	The id corresponding to the replace persistent volume claim task.
taskStatus string	The status of the operation.

Delete a persistent volume claim

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/persistentvolumeclaims/cmc-staging-mysql/cmc-stg?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/persistentvolumeclaims/:id?cluster_id=:cluster_id

Delete a perstent volume claim from a given environment.

Required
cluster_id string	The id of the cluster in which to get the perstent volume claim.

Attributes
taskId string	The id corresponding to the delete persistent volume claim task.
taskStatus string	The status of the operation.

Access control

Service accounts

List service accounts

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
      "metadata": {
        "name": "vpnkit-controller",
        "namespace": "kube-system",
        "selfLink": "/api/v1/namespaces/kube-system/serviceaccounts/vpnkit-controller",
        "uid": "b9afa8a8-3d64-4605-959f-12bb5c6cfba2",
        "resourceVersion": "481",
        "creationTimestamp": "2020-09-18T14:47:48Z",
        "annotations": {
          "kubectl.kubernetes.io/last-applied-configuration": "{\"apiVersion\":\"v1\",\"kind\":\"ServiceAccount\",\"metadata\":{\"annotations\":{},\"name\":\"vpnkit-controller\",\"namespace\":\"kube-system\"}}\n"
        }
      },
      "secrets": [
        {
          "name": "vpnkit-controller-token-hl674"
        }
      ]
    }
  ]
}

GET /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id

Retrieve a list of all service accounts in a given environment.

Attributes
id string	The id of the service account.
metadata.annotations map	The annotations of the service account.
metadata object	The metadata of the service account.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace in which the service account is created.
metadata.uid object	The UUID of the service account.
metadata.secrets List<object>	The secrets of the service account.
secretsSize integer	The number of secrets of the service account.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a service account

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/serviceaccount-name/serviceaccount-namespace?cluster_id=:cluster_id"

The above command returns a JSON structured like this:

{
  "data": {
            "id": "default",
            "age": "1w5d",
            "secretsSize": 1,
            "metadata": {
              "creationTimestamp": "2020-09-18T10:46:40.000-04:00",
              "name": "default",
              "namespace": "default",
              "uid": "80a0de4d-a187-44c3-b691-1481220a5817"
            },
            "secrets": [
              {
                "name": "default-token-lrth9"
              }
            ]
          },
          "fieldTransitions": {},
          "operations": []
        }

GET /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id

Retrieve a service account and all its info in a given environment.

Attributes
id string	The id of the service account.
metadata object	The metadata of the service account.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace in which the service account is created.
metadata.uid object	The UUID of the service account.
metadata.secrets List<object>	The secrets of the service account.
secretsSize integer	The number of secrets of the service account.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a service account

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "apiVersion": "v1",
    "metadata": {
        "name": "service-account-name",
        "namespace": "default"
    }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/serviceaccounts?cluster_id=:cluster_id

Create a service account in a given environment.

Required Attributes
apiVersion string	The api version (versioned schema) of the service account.
metadata object	The metadata of the service account.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace of the service account.

Return value:

Attributes
taskId string	The id corresponding to the create service account task.
taskStatus string	The status of the operation.

Replace a service account

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/service-account-name/namespace-name?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "metadata": {
        "name": "service-account-name",
        "namespace": "namespace-name"
    }
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id

Replace a service account in a given environment.

Required Attributes
metadata object	The metadata of the service account.
metadata.name string	The name of the service account.
metadata.namespace string	The namespace of the service account.

Return value:

Attributes
taskId string	The id corresponding to the create service account task.
taskStatus string	The status of the operation.

Delete a service account

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/serviceaccounts/my-service-account/my-namespace?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/serviceaccounts/:id?cluster_id=:cluster_id

Delete a service account from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the service account.

Attributes
taskId string	The id corresponding to the delete service account task.
taskStatus string	The status of the operation.

Roles

List (namespace) Roles

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "role-id",
            "age": "1w4d",
            "metadata": {
                "creationTimestamp": "2020-09-18T10:01:26.000-04:00",
                "name": "kubeadm:bootstrap-signer-clusterinfo",
                "namespace": "kube-public",
                "uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a46"
            },
            "rules": [
                {
                    "apiGroups": [],
                    "resourceNames": [],
                    "resources": [],
                    "verbs": []
                }
            ]
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/roles?cluster_id=:cluster_id

Retrieve a list of all roles in a given environment.

Attributes
id string	The id of the role.
metadata object	The metadata of the role.
metadata.creationTimestamp string	The date of creation of the service account as a string.
metadata.name string	The name of the role.
metadata.namespace string	The namespace in which the role is created.
metadata.uid object	The UUID of the role.
rules array	The array of rules associated with this role.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a role

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/role-name/role-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "kubeadm:bootstrap-signer-clusterinfo",
        "age": "1w4d",
        "apiVersion": "rbac.authorization.k8s.io/v1",
        "kind": "Role",
        "metadata": {
            "creationTimestamp": "2020-09-18T10:01:26.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "57ef0321-e44a-43c9-9f2a-e448c3a66a47"
        },
        "rules": [
            {
                "apiGroups": [],
                "resourceNames": [],
                "resources": [],
                "verbs": []
            }
        ]
    }
}

GET /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id

Retrieve a role and all its info in a given environment.

Attributes
id string	The id of the role.
apiVersion string	The API version used to retrieve this role.
metadata object	The metadata of the role.
rules array	The array of rules associated with this role.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a role

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles?cluster_id=:cluster_id"
  Content-Type: application/json
  {
   "apiVersion": "rbac.authorization.k8s.io/v1",
   "kind": "Role",
   "namespace": "default",
   "name": "test-name",
   "metadata": {
      "namespace": "default",
      "name": "test-name"
   },
   "rules": [
      {
         "apiGroups": [
            ""
         ],
         "resources": [
            "resource"
         ],
         "verbs": [
            "get",
            "watch"
         ]
      }
   ]
}

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/roles?cluster_id=:cluster_id

Create a role in a given environment.

Attributes
id string	The id of the role.
apiVersion string	The API version used to create this role.
metadata.name string	The name of the role.
metadata.namespace string	The namespace of the role.
rules array	The array of rules associated with this role.

Return value:

Attributes
taskId string	The id corresponding to the create role task.
taskStatus string	The status of the operation.

Replace a role

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/role-name/namespace-name?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "metadata": {
        "name": "role-name",
        "namespace": "namespace-name"
    }
    "rules": [
      {
         "apiGroups": [
            ""
         ],
         "resources": [
            "resource"
         ],
         "verbs": [
            "get",
            "watch",
            "..."
         ]
      }
   ]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id

Replace a role in a given environment.

Required Attributes
metadata object	The metadata of the role.
metadata.name string	The name of the role.
metadata.namespace string	The namespace of the role.
metadata.namespace string	The namespace of the role.

Optional Attributes
rules array	The array of rules associated with this role.

Return value:

Attributes
taskId string	The id corresponding to the replace role operation.
taskStatus string	The status of the operation.

Delete a role

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/roles/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/roles/:id?cluster_id=:cluster_id

Delete a role from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the role.

Attributes
taskId string	The id corresponding to the delete role task.
taskStatus string	The status of the operation.

Role bindings

List (namespace) role bindings

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{


"data": {
        "entity": {
          "id": "kubeadm:bootstrap-signer-clusterinfo",
          "age": "1w5d",
          "metadata": {
            "creationTimestamp": "2020-09-18T10:46:32.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
          },
          "roleRef": {
            "apiGroup": "rbac.authorization.k8s.io",
            "kind": "Role",
            "name": "kubeadm:bootstrap-signer-clusterinfo"
          },
          "subjects": [
            {
              "apiGroup": "rbac.authorization.k8s.io",
              "kind": "User",
              "name": "system:anonymous"
            }
          ]
        },
        "fieldTransitions": {},
        "operations": []
      },
}

GET /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id

Retrieve a list of all role bindings in a given environment.

Attributes
id string	The id of the role binding.
metadata object	The metadata of the role binding.
metadata.creationTimestamp string	The date of creation of the role binding as a string.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace in which the role binding is created.
metadata.uid object	The UUID of the role binding.

Note that the list is not complete, since it is refering to the kubernetes api details.

Get a role binding

curl -X GET </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/rolebinding-name/rolebinding-namespace?cluster_id=projects/cmc-k8s-enabled-llb/locations/us-central1-a/clusters/standard-cluster-1"

The above command returns a JSON structured like this:

{


"data": {

"id": "kubeadm:bootstrap-signer-clusterinfo",
          "age": "1w5d",
          "metadata": {
            "creationTimestamp": "2020-09-18T10:46:32.000-04:00",
            "name": "kubeadm:bootstrap-signer-clusterinfo",
            "namespace": "kube-public",
            "uid": "4fcfe5b9-a1c3-4b3b-9cb6-6df4a1da945f"
          },
          "roleRef": {
            "apiGroup": "rbac.authorization.k8s.io",
            "kind": "Role",
            "name": "kubeadm:bootstrap-signer-clusterinfo"
          },
          "subjects": [
            {
              "apiGroup": "rbac.authorization.k8s.io",
              "kind": "User",
              "name": "system:anonymous"
            }
          ]
        },
        "fieldTransitions": {},
        "operations": []
      },
}

GET /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id

Retrieve a role binding and all its info in a given environment.

Attributes
id string	The id of the role binding.
apiVersion string	The API version used to retrieve this role binding.
metadata object	The metadata of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	The array of subjects associated with this role binding.

Note that the list is not complete, since it is refering to the kubernetes api details.

Create a role binding

curl -X POST </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "kind": "Rolebinding",
    "metadata": {
        "name": "rolebinding-name",
        "namespace": "namespace-name"
    },
    "roleRef": {
        "apiGroup": "rbac.authorization.k8s.io",
        "kind": "Role",
        "name": "role-name"
    },
    "subjects": [
        {
            "kind": "ServiceAccount",
            "name": "service-account-name",
            "namespace": "service-account-namespace"
        },
        {
            "kind": "Group",
            "name": "group-name",
            "namespace": "group-namespace"
        },
        {
            "kind": "User",
            "name": "user-name",
        }


]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/rolebindings?cluster_id=:cluster_id

Create a role binding in a given environment.

Required Attributes
metadata object	The metadata of the role binding.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts.

Return value:

Attributes
taskId string	The id corresponding to the create role binding task.
taskStatus string	The status of the operation.

Replace a role binding

curl -X PUT </span>
  -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/rolebinding-name/namespace-name?cluster_id=:cluster_id"
  Content-Type: application/json
  {
    "metadata": {
        "name": "service-account-name",
        "namespace": "namespace-name"
    },
    "roleRef": {
      "apiGroup": "",
      "kind": "Role",
      "name": "role-name"
    },
    "subjects": [
      {
        "kind": "ServiceAccount",
        "name": "default",
        "namespace": "default"
      },
      {
        "kind": "user",
        "name": "user1",
      }
    ]
  }

The above command returns a JSON structured like this:

{
  "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id

Replace a role binding in a given environment.

Required Attributes
metadata object	The metadata of the role binding.
metadata.name string	The name of the role binding.
metadata.namespace string	The namespace of the role binding.
roleRef object	The role to bind. Can reference a Role in the current namespace or a ClusterRole in the global namespace.
subjects array	Subjects hold references to the objets the role applies to. Can be users, groups, or service accounts.

Return value:

Attributes
taskId string	The id corresponding to the replace role binding operation.
taskStatus string	The status of the operation.

Delete a role binding

curl -X DELETE </span>
   -H "MC-Api-Key: your_api_key" </span>
   "https://cloudmc_endpoint/api/v1/services/a_service/an_environment/rolebindings/default-token-xxxmt/default?cluster_id=a_cluster_id"

The above command returns a JSON structured like this: json { "taskId": "1542bd45-4732-419b-87b6-4ea6ec695c2b", "taskStatus": "PENDING" } DELETE /services/:service_code/:environment_name/rolebindings/:id?cluster_id=:cluster_id

Delete a role binding from a given environment.

Required
cluster_id string	The id of the cluster in which to delete the role binding.

Attributes
taskId string	The id corresponding to the delete role binding task.
taskStatus string	The status of the operation.

Swift plugin

The Swift plugin provides endpoints for carrying out operations on Swift containers and objects. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of Swift.

Containers or Buckets

Create and manage your containers/buckets.

List containers/buckets

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/swift/example/buckets"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "private",
      "name": "private",
      "isPublic": false,
      "displaySize": {
        "value": "0",
        "unitKey": "units.filesizes.B"
      },
      "size": 0,
      "objectCount": 0,
      "accessType": "private",
      "locked": false,
      "storagePolicy": "Quebec"
    },
    {
      "id": "public",
      "name": "public",
      "isPublic": true,
      "displaySize": {
        "value": "81",
        "unitKey": "units.filesizes.B"
      },
      "size": 81,
      "objectCount": 6,
      "accessType": "public",
      "locked": false,
      "storagePolicy": "Quebec"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/buckets

Retrieve a list of all containers in a given environment.

Attributes
id string	The id of the container.
name string	The name of the container.
isPublic boolean	Specifies if the container is public or not.
displaySize Object	Object containing the information to display the size in the UI.
size string	The size in bytes of the container.
objectCount string	The number of object which are part of the container.
accessType string	The access type of the container. It can either be public or private.
locked string	Identify if the container is locked or not.
storePolicy string	The store policy applying to the container.

Retrieve a container

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/swift/example/buckets/private"

The above command returns a JSON structured like this:

{
  "id": "private",
  "name": "private",
  "isPublic": false,
  "displaySize": {
    "value": "0",
    "unitKey": "units.filesizes.B"
  },
  "size": 0,
  "objectCount": 0,
  "accessType": "private",
  "locked": false,
  "storagePolicy": "Quebec"
}

GET /services/:service_code/:environment_name/buckets/:id

Retrieve a container in a given environment.

Attributes
id string	The id of the container.
name string	The name of the container.
isPublic boolean	Specifies if the container is public or not.
displaySize Object	Object containing the information to display the size in the UI.
size string	The size in bytes of the container.
objectCount string	The number of object which are part of the container.
accessType string	The access type of the container. It can either be public or private.
locked boolean	Identify if the container is locked or not.
storePolicy string	The store policy applying to the container.

Create a container

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/swift/example/buckets"

Request body example:

{
  "name": "newBucket",
  "isPublic": true
}

POST /services/:service_code/:environment_name/buckets

Create a new container.

Required
name string	The name of the container. It cannot exceed 256 characters and cannot contain '/'.

Optional
isPublic boolean	Specifies if the container is public or private. The default value is false.

Delete a container

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/swift/example/buckets/containerToDelete"

DELETE /services/:service_code/:environment_name/buckets/:id

Delete an existing container.

Rename a container

Rename the container to a new name.

curl -X POST \
   -H "Content-Type: application/json" \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/swift/example/buckets/containerToRename?operation=rename"

Request body example:

{
  "name": "newContainerName"
}

POST /services/:service_code/:environment_name/buckets/:id?operation=rename

Required
name string	The new name of the container.

Objects

Create and manage your objects.

Preview objects

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/swift/my-env/objects/my-private-bucket/my-object.jpg/redirect?operation=preview"

GET /services/:service_code/:environment_name/objects/:id/redirect

Preview both public and private objects. Previews of private objects will generate a temporary URL that provides GET access for limited time. The generated URL will expire after one hour.

StackPath plugin

The StackPath plugin provides endpoints for carrying out operations on CloudMC Edge computing entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC on top of StackPath.

Edge compute

Workloads

StackPath Edge Computing uses the concept of workloads to organize different applications. A workload can consist of one container or virtual machine image that is deployed to one or many locations.

Deploy and manage your workloads.

List workloads

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/workloads"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "name": "container-workload",
      "stackId": "a397735b-66d2-49ba-b665-e77acb944481",
      "slug": "container-workload",
      "version": "1",
      "created": "2021-02-22T17:32:27.202428099Z",
      "type": "CONTAINER",
      "network": "default",
      "cpu": "1",
      "memory": "2Gi",
      "isRemoteManagementEnabled": false,
      "image": "nginx",
      "addImagePullCredentialsOption": false,
      "environmentVariables": [
        {
          "key": "USER",
          "value": "my-user"
        }
      ],
      "secretEnvironmentVariables": [
        {
          "key": "PASSWORD",
          "value": "[REDACTED]"
        }
      ],
      "addAnyCastIpAddress": false,
      "anycastIpAddress": "185.85.196.7",
      "commands": [
        "/bin/sh -c \"sleep 50\""
      ],
      "specs": "SP-1",
      "persistentStorages" : [
        {
          "path": "/lib/data/newFolder",
          "size": 1,
        }  
      ],
      "deployments": [
        {
          "name": "deployment-lax",
          "pops": [
            "LAX"
          ],
          "enableAutoScaling": true,
          "cpuUtilization": 50,
          "minInstancesPerPop": "1",
          "maxInstancesPerPop": "2"
        }, {
          "name": "deployment-mia",
          "pops": [
            "MIA"
          ],
          "enableAutoScaling": false,
          "instancesPerPop": "1",
          "cpuUtilization": 0,
        }
      ],
      "id": "af951a00-5d1f-4c0a-85a4-b0714e833cd1",
      "status": "ACTIVE"
    }, {
      "id": "419be644-b2e7-4574-aad9-52e1cc0e6199",
      "name": "vm-workload",
      "stackId": "4f246958-595d-4ead-ae56-a88cff334b97",
      "slug": "vm-workload",
      "version": "10",
      "created": "2020-11-27T20:11:09.563675315Z",
      "type": "VM",
      "network": "default",
      "specs": "SP-1",
      "cpu": "1",
      "memory": "2Gi",
      "isRemoteManagementEnabled": false,
      "image": "stackpath-edge/centos-7:v202007311835",
      "addAnyCastIpAddress": false,
      "anycastIpAddress": "None",
      "firstBootSshKey": "ssh-rsa...",
      "persistentStorages" : [
        {
          "path": "/lib/data/newFolder",
          "size": 1,
        }  
      ],
      "deploymentName": "deployment-name",
      "deploymentPops": [
        "YYZ"
      ],
      "enableAutoScaling": false,
      "deploymentInstancePerPops": 3,
      "status": "ACTIVE"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/workloads

Retrieve a list of all workloads in a given environment.

Attributes
addImagePullCredentialsOption boolean	It is used to indicate if additional credentials to pull container image are provided or not. Only applicable to workloads of type 'CONTAINER'.
anycastIpAddress string	The Anycast IP address assigned to a workload. If there is no IP assigned to the workload then the value of this attribute will be None.
commands Array[string]	The commands that start a container. Only applicable to workloads of type 'CONTAINER'.
containerEmail string	The email address to use for the docker registry account. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'.
containerServer string	The server that the credentials should be used with. This value will default to the docker hub registry when not set. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'.
containerUsername string	The username used to authenticate the image pull. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'.
cpu string	The number of vCPUs for the workload's instance.
created string	Creation timestamp of the workload.
deployments.cpuUtilization int	The percentage of CPU utilization. Only applicable if autoscaling is enabled.
deployments.enableAutoScaling boolean	Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are shown.
deployments.instancesPerPop int	The number of instances per point of presence. Only applicable if autoscaling is not enabled.
deployments.maxInstancesPerPop int	The maximum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50.
deployments.minInstancesPerPop int	The minimum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50.
deployments.name string	The name of the deployment.
deployments.pops Array[string]	The points of presence of a deployment. In the regex format [A-Z]{3, 3}.
deployments Array[Object]	The list of deployment targets.
environmentVariables.key string	The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
environmentVariables.value string	An environment variable's value.
environmentVariables Array[Object]	A list of environment variables. Only applicable to workloads of type 'CONTAINER'.
firstBootSshKey string	The ssh key(s) for the VM image. Keys are delimited by a newline, \n. Only applicable to workloads of type 'VM'.
id string	A workload's unique identifier.
image string	The workload's instance operating system image.
isRemoteManagementEnabled boolean	Specifies if remote management is enabled on workload instance or not.
memory string	The memory size for the workload's instance.
name string	The display name of the workload.
network string	Network interfaces to bind to the workload's instances.
persistentStorages Array[Object]	Persistent storage volumes used by the workload.
persistentStorages.path string	The path in an instance to mount a volume.
persistentStorages.size int	The size of the mounted volume (in GB).
secretEnvironmentVariables.key string	The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
secretEnvironmentVariables.value string	A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret.
secretEnvironmentVariables Array[Object]	A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'.
slug string	A workload's programmatic name. Workload slugs are used to build its instances names.
specs string	Specification type for resources which are allocated to each instance in a workload.
stackId string	The ID of the stack that a workload belongs to.
status string	The status of the workload. It can be either ACTIVE or DISABLED.
type string	Specify whether a workload is a VM-based workload or container-based.
userData string	User data compatible with cloud-init to be run on the workload's instances.
version string	A version number for the workload. Versions start at 1 when they are created and increment by 1 every time they are updated.

Retrieve a workload

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"

The above command returns a JSON structured like this:

{
  "data": {
    "name": "container-workload",
    "stackId": "a397735b-66d2-49ba-b665-e77acb944481",
    "slug": "container-workload",
    "version": "1",
    "created": "2021-02-22T17:32:27.202428099Z",
    "type": "CONTAINER",
    "network": "default",
    "cpu": "1",
    "memory": "2Gi",
    "userData":"package-upgrade: true",
    "isRemoteManagementEnabled": false,
    "image": "nginx",
    "addImagePullCredentialsOption": false,
    "environmentVariables": [
      {
        "key": "USER",
        "value": "my-user"
      }
    ],
    "secretEnvironmentVariables": [
      {
        "key": "PASSWORD",
        "value": "[REDACTED]"
      }
    ],
    "addAnyCastIpAddress": false,
    "anycastIpAddress": "None",
    "commands": [
      "/bin/sh -c \"sleep 50\""
    ],
    "specs": "SP-1",
    "persistentStorages" : [
      {
        "path": "/lib/data/newFolder",
        "size": 1,
      }  
    ],
    "deployments": [
      {
        "name": "deployment-lax",
        "pops": [
          "LAX"
        ],
        "enableAutoScaling": true,
        "cpuUtilization": 50,
        "minInstancesPerPop": "1",
        "maxInstancesPerPop": "2"
      }, {
        "name": "deployment-mia",
        "pops": [
          "MIA"
        ],
        "enableAutoScaling": false,
        "instancesPerPop": "1",
        "cpuUtilization": 0,
      }
    ],
    "id": "af951a00-5d1f-4c0a-85a4-b0714e833cd1",
    "status": "ACTIVE"
  }
}

GET /services/:service_code/:environment_name/workloads/:id

Retrieve a workload in a given environment.

Attributes
addImagePullCredentialsOption boolean	It is used to indicate if additional credentials to pull container image are provided or not. Only applicable to workloads of type 'CONTAINER'.
anycastIpAddress string	The Anycast IP address assigned to a workload. If there is no IP assigned to the workload then the value of this attribute will be None.
commands Array[string]	The commands that start a container. Only applicable to workloads of type 'CONTAINER'.
containerEmail string	The email address to use for the docker registry account. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'.
containerServer string	The server that the credentials should be used with. This value will default to the docker hub registry when not set. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'.
containerUsername string	The username used to authenticate the image pull. Only applicable to workloads of type 'CONTAINER' and addImagePullCredentialsOption is 'true'.
cpu string	The number of vCPUs for the workload's instance.
created string	Creation timestamp of the workload.
deployments.cpuUtilization int	The percentage of CPU utilization. Only applicable if autoscaling is enabled.
deployments.enableAutoScaling boolean	Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are shown.
deployments.instancesPerPop int	The number of instances per point of presence. Only applicable if autoscaling is not enabled.
deployments.maxInstancesPerPop int	The maximum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50.
deployments.minInstancesPerPop int	The minimum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50.
deployments.name string	The name of the deployment.
deployments.pops Array[string]	The points of presence of a deployment. In the regex format [A-Z]{3, 3}.
deployments Array[Object]	The list of deployment targets.
environmentVariables.key string	The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
environmentVariables.value string	An environment variable's value.
environmentVariables Array[Object]	A list of environment variables. Only applicable to workloads of type 'CONTAINER'.
firstBootSshKey string	The ssh key(s) for the VM image. Keys are delimited by a newline, \n. Only applicable to workloads of type 'VM'.
id string	A workload's unique identifier.
image string	The workload's instance operating system image.
isRemoteManagementEnabled boolean	Specifies if remote management is enabled on workload instance or not.
memory string	The memory size for the workload's instance.
name string	The display name of the workload.
network string	Network interfaces to bind to the workload's instances.
persistentStorages Array[Object]	Persistent storage volumes used by the workload.
persistentStorages.path string	The path in an instance to mount a volume.
persistentStorages.size int	The size of the mounted volume (in GB).
secretEnvironmentVariables.key string	The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
secretEnvironmentVariables.value string	A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret.
secretEnvironmentVariables Array[Object]	A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'.
slug string	A workload's programmatic name. Workload slugs are used to build its instances names.
specs string	Specification type for resources which are allocated to each instance in a workload.
stackId string	The ID of the stack that a workload belongs to.
status string	The status of the workload. It can be either ACTIVE or DISABLED.
type string	Specify whether a workload is a VM-based workload or container-based.
userData string	User data compatible with cloud-init to be run on the workload's instances.
version string	A version number for the workload. Versions start at 1 when they are created and increment by 1 every time they are updated.

Create a workload

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/workloads"

Request body example for a VM Workload type:

{
  "name":"vm-workload",
  "slug":"vm-workload",
  "type":"VM",
  "image":"stackpath-edge/centos-7-cpanel:v201905241955",
  "addAnyCastIpAddress":false,
  "ports": [
    {
      "publicPort": "80",
      "protocol": "TCP",
      "publicPortDesc": "rule-name"
    }
  ],
  "firstBootSshKey":"ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQDcYr9OnzsDfYVW2I1kX/iYJ0mPG490bI5mbxbOAKPLMuWLguxRohX804j1XbwZJ+Sna+9rSfxaYA8vgd1MoYX10l9cnMLx/MMbYp4ZquauN4pGY3WoDeCqsTss3VUMW+7RFBILpU3SJTlDV02FI36D3IXb4A8XymCyU3KC99XXTfTQsuKC+WFRMsTWtklrasqCVd5yEG90i/aJc6A3TZGOYgPFNEeVYvNDaJmIkb3y4FfShoBIMgZRt0ay7SvWZUvyfvyNmK5W9ePdhZZ58R+7tQNmCzjQ4v0suWRuGJ/XL3+03w3HEsDdQx+noL+R+qAjoNFwc0spBBhJK+Q4ADqr nothing@gmail.com \nssh-rsa...",
  "userData":"package-upgrade: true",
  "specs":"SP-1",
  "persistentStorages" : [
    {
      "path": "/lib/data/newFolder",
      "size": 1,
    }
  ],
  "deployments": [
    {
      "name": "deployment-name",
      "enableAutoScaling": false,
      "pops": ["MIA"],
      "instancesPerPop": "1"
    }
  ]
}

Request body example for a CONTAINER Workload type:

{
  "type": "CONTAINER",
  "name": "container-workload",
  "slug": "container-workload",
  "image": "nginx",
  "addAnyCastIpAddress": false,
  "ports": [
    {
      "publicPort": "80",
      "protocol": "TCP",
      "publicPortDesc": "rule-name"
    }
  ],
  "specs": "SP-1",
  "persistentStorages" : [
    {
      "path": "/lib/data/newFolder",
      "size": 1,
    }  
  ],
  "userData":"package-upgrade: true",
  "commands": [
    "/bin/sh -c \"sleep 50\""
  ],
  "environmentVariables": [
    {
      "key": "USER",
      "value": "my-user"
    }
  ],
  "secretEnvironmentVariables": [
    {
      "key": "PASSWORD",
      "value": "my-password"
    }
  ],
  "deployments": [
    {
      "name": "deployment-mia",
      "enableAutoScaling": false,
      "pops": [
        "MIA"
      ],
      "instancesPerPop": "1"
    },
    {
      "name": "deployment-lax",
      "pops": [
        "LAX"
      ],
      "enableAutoScaling": true,
      "minInstancesPerPop": 1,
      "maxInstancesPerPop": 2,
      "cpuUtilization": 50
    }
  ]
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/workloads

Create a new workload in a given environment.

Required
deployments.enableAutoScaling boolean	Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are required.
deployments.name string	The name of the deployment.
deployments.pops Array[string]	The points of presence of a deployment. In the regex format [A-Z]{3, 3}.
deployments Array[Object]	The list of deployment targets.
firstBootSshKey string	If creating a VM-based workload, SSH keys are required. Multiple SSH keys can be separated by newlines \n.
image string	Either the location of a Docker image to run as a container or the image to use for the virtual machine. If for a virtual machine, this is in the format of /[:]. If the image tag portion is omitted, 'default' is assumed which is the most recently created, ready, and non-deprecated image of that slug. A set of common images is present on the 'stackpath-edge' stack.
name string	The name of the workload. The workload name must not exceed 18 characters.
specs string	Specification type for resources which are allocated to each instance in a workload. Supported specifications are SP-1 (1 vCPU, 2 GB RAM),SP-2 (2 vCPU, 4 GB RAM),SP-3 (2 vCPU, 8GB RAM),SP-4 (4 vCPU, 16 GB RAM),SP-5 (8 vCPU, 32 GB RAM).
type string	Specify whether a workload is a VM-based workload or container-based. Can be either VM or CONTAINER.

Optional
addAnyCastIpAddress boolean	Option to AnyCast IP Address.
addImagePullCredentialsOption boolean	It is used to indicate if additional credentials to pull container image are provided or not.
commands Array[string]	The commands that start a container. Only applicable to workloads of type 'CONTAINER'. Commands cannot be updated or removed after workload creation.
containerEmail string	The email address to use for the docker registry account
containerPassword string	The password used to authenticate the image pull.
containerServer string	The server that the credentials should be used with. This value will default to the docker hub registry when not set.
containerUsername string	The username used to authenticate the image pull.
deployments.cpuUtilization int	The percentage of CPU utilization. Only applicable if autoscaling is enabled.
deployments.instancesPerPop int	The number of instances per point of presence. Only applicable if autoscaling is not enabled.
deployments.maxInstancesPerPop int	The maximum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50.
deployments.minInstancesPerPop int	The minimum number of instances per PoP. Only applicable if autoscaling is enabled. Should be greater than zero and less than 50.
environmentVariables.key string	The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
environmentVariables.value string	An environment variable's value.
environmentVariables Array[Object]	A list of environment variables. Only applicable to workloads of type 'CONTAINER'.
persistentStorages Array[Object]	Persistent storage volumes used by the workload.
persistentStorages.path string	The path in an instance to mount a volume.
persistentStorages.size int	The size of the mounted volume (in GB).
ports.protocol string	Protocol for the network policy rule. Supported protocols are: TCP, UDP and TCP_UDP.
ports.publicPort string	A single port, such as 80 or a port range, such as 1024-65535 for which a network policy rule will be created for the workload.
ports.publicPortDesc string	A summary of what the network policy rule does or a name for it. It is highly recommended to give a unique description to easily identify a network policy rule. Defaults to an empty string if not provided.
ports.publicPortSrc string	A subnet that will define all the IPs allowed by the network policy rule. Defaults to 0.0.0.0/0 if not specified.
ports Array[Object]	A list of network interfaces that will be created for each workload instance.
secretEnvironmentVariables.key string	The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
secretEnvironmentVariables.value string	A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret.
secretEnvironmentVariables Array[Object]	A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'.
slug string	A workload's programmatic name. Workload slugs are used to build its instances names. If not provided, defaults to workload's name. It must not exceed 18 characters.
userData string	User data compatible with cloud-init to be run on the workload's instances. This should only be set for a VM-based workload.

Edit a workload

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"

Request body example for a VM Workload type:

{
  "name": "my-vm-workload",
  "type": "VM",
  "specs": "SP-1",
  "userData":"package-upgrade: true",
  "deployments": [
    {
      "name": "toronto-1",
      "pops": [
        "YYZ"
      ],
      "enableAutoScaling": true,
      "minInstancesPerPop": 1,
      "maxInstancesPerPop": 2,
      "cpuUtilization": 50
    }
  ]
}

Request body example for a CONTAINER Workload type:

{
  "name": "my-container-workload",
  "type": "CONTAINER",
  "image": "redis:alpine",
  "secretEnvironmentVariables": [
    {
      "key": "PASSWORD",
      "value": "my-password"
    },
    {
      // set value to [REDACTED] to preserve existing secret
      "key": "PRIVATE-KEY",
      "value": "[REDACTED]"
    }
  ],
  "addImagePullCredentialsOption": true,
  "containerUsername": "username",
  "containerServer": "container.server.io",
  "containerEmail": "myemail@email.com",
  "containerPassword": "my-password",
  "specs": "SP-2",
  "deployments": [
    {
      "name": "toronto-1",
      "enableAutoScaling": false,
      "pops": [
        "YYZ"
      ],
      "instancesPerPop": "1"
    }
  ]
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/workloads/:id

Edit a workload in a given environment.

Required
deployments.enableAutoScaling boolean	Specifies if autoscaling is enabled. If enabled, then cpuUtilization , minInstancesPerPop and maxInstancesPerPop are required.
deployments.name string	The name of the deployment.
deployments.pops Array[string]	The points of presence of a deployment. In the regex format [A-Z]{3, 3}.
deployments Array[Object]	The list of deployment targets.
image string	The location of a Docker image to run as a container. Only editable when type is equal to CONTAINER.
name string	The name of the workload. The workload name must not exceed 18 characters.
specs string	Specification type for resources which are allocated to each instance in a workload.
type string	Specify whether a workload is a VM-based workload or container-based. Can be either VM or CONTAINER.

Optional
addImagePullCredentialsOption boolean	It is used to indicate if additional credentials to pull container image are provided or not. Only available when type is equal to CONTAINER.
containerEmail string	The password that should be used to authenticate the image pull. Only available when type is equal to CONTAINER.
containerPassword string	The password that should be used to authenticate the image pull. Only available when type is equal to CONTAINER.
containerServer string	The server that the credentials should be used with. This value will default to the docker hub registry when not set. Only available when type is equal to CONTAINER.
containerUsername string	The username that should be used for authenticate the image pull. Only available when type is equal to CONTAINER.
deployments.cpuUtilization integer	The average CPU utlilization threshold to be reached before deploying a new instance. Only required if autoscaling is enabled.
deployments.instancesPerPop integer	The number of deployments per point of presence. Only required if autoscaling is not enabled.
deployments.maxInstancesPerPop integer	The maximum number of instances per point of presence. Only required if autoscaling is enabled.
deployments.minInstancesPerPop integer	The minimum number of instances per point of presence. Only required if autoscaling is enabled.
environmentVariables.key string	The location to obtain a value for an environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
environmentVariables.value string	An environment variable's value.
environmentVariables Array[Object]	A list of environment variables. Only applicable to workloads of type 'CONTAINER'.
secretEnvironmentVariables.key string	The location to obtain a value for a secret environment variable. When editing a workload, include keys you wish to preserve. Keys not included in the body will be removed.
secretEnvironmentVariables.value string	A secret environment variable's value. When editing a workload, setting an existing environment variable's value to [REDACTED] will preserve the existing secret.
secretEnvironmentVariables Array[Object]	A list of sensitive environment variables. Only applicable to workloads of type 'CONTAINER'.
userData string	User data compatible with cloud-init to be run on the workload's instances. This should only be set for a VM-based workload.

Delete a workload

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/workloads/:id

Delete a workload in a given environment.

Attributes
taskId string	The task id related to the workload deletion.
taskStatus string	The status of the operation.

Edit workload settings

Change a workload specific settings in a given environment. At the moment, only isRemoteManagementEnabled is supported for this operation. Any other attributes will be ignored.

curl -X PATCH \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/workloads/1b932678-1038-4ab4-9fa4-c4c06e696e20"

Request body example:

{
  "isRemoteManagementEnabled": false
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

PATCH /services/:service_code/:environment_name/workloads/:id

Instances

Manage your workload instances.

List instances

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/instances?workloadId=e485fe8c-e1de-40f7-b3b3-a43700441e0e"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "stackId": "asd04459-1ccf-4a0d-8aaa-98d0f52dd2f3",
      "workloadId": "e485fe8c-e1de-40f7-b3b3-a43700441e0e",
      "name": "test-dep1-lax-0",
      "ipAddress": "10.128.16.2",
      "publicIpAddress": "151.139.71.25",
      "location": "Los Angeles",
      "createdDate": "2020-11-10T16:52:15Z",
      "startedDate": "2020-11-10T16:52:15Z",
      "id": "e485fe8c-e1de-40f7-b3b3-a43700441e0e/instance-name-1",
      "status": "RUNNING"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/instance?workloadId=:workloadId

Retrieve a list of all workload instance in a given environment for a given workload ID.

Query Params
workloadId string	The workload ID to get the instances for. It is mandatory.

Attributes
id string	The instance ID. It is the combination of /.
name string	The instance name.
status string	The instance status. Possible values are: RUNNING, STARTING, SCHEDULING.
stackId UUID	The stack ID to which this instance belongs.
workloadId UUID	The workload ID to which this instance belongs.
ipAddress string	The internal IP address associated with the instance.
publicIpAddress string	The public IP address associated with the instance.
location string	The instance location.
createdDate string	The instance creation date.
startedDate string	The instance started date.

Retrieve an instance

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/instances/e485fe8c-e1de-40f7-b3b3-a43700441e0e/instance-name-1"

The above command returns a JSON structured like this:

{
  "data": {
    "stackId": "asd04459-1ccf-4a0d-8aaa-98d0f52dd2f3",
    "workloadId": "e485fe8c-e1de-40f7-b3b3-a43700441e0e",
    "name": "instance-name-1",
    "ipAddress": "10.128.16.2",
    "publicIpAddress": "151.139.71.25",
    "location": "Los Angeles",
    "createdDate": "2020-11-10T16:52:15Z",
    "startedDate": "2020-11-10T16:52:15Z",
    "id": "e485fe8c-e1de-40f7-b3b3-a43700441e0e/instance-name-1",
    "status": "RUNNING"
  }
}

GET /services/:service_code/:environment_name/instances/:id

Retrieve an instance in a given environment with the specific ID.

Attributes
id string	The instance ID. It is the combination of /.
name string	The instance name.
status string	The instance status. Possible values are: RUNNING, STARTING, SCHEDULING.
stackId UUID	The stack ID to which this instance belongs.
workloadId UUID	The workload ID to which this instance belongs.
ipAddress string	The internal IP address associated with the instance.
publicIpAddress string	The public IP address associated with the instance.
location string	The instance location.
createdDate string	The instance creation date.
startedDate string	The instance started date.

Restart an instance

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/instances/workload-id1/instance-name-1?operation=restart"

POST /services/:service_code/:environment_name/instances/:id?operation=restart

Restart an instance in a given environment with the specific ID.

Access the console of an instance

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/instances/workload-id1/instance-name-1?operation=accessconsole"

Request body example(s):

{
  "vmRemoteAccessType": "VNC"
}

The above command(s) return(s) JSON structured like this:

{
  "taskId": "c50390c7-9d5b-4af4-a2da-e2a2678a83e8",
  "taskStatus": "SUCCESS"
}

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/tasks/c50390c7-9d5b-4af4-a2da-e2a2678a83e8"

The above command(s) return(s) JSON structured like this:

{
  "data": {
    "id": "f44382a4-82e6-45f6-9153-6aa5ec69eafd",
    "status": "SUCCESS",
    "created": "2021-04-20T20:58:59.952881-04:00",
    "result": {
      "clientId": "1e15e2050fe44771c5dd82dcf07c",
      "sshCommand": "ssh -p 9600 -t test-stack-8x5ppioikq-env.w-jdias-cmp-wi-jdias-edh-ord-0.container-0.0cbc2e63dffa4fa6b183fafeeb575c95@container-console.edgeengine.io /bin/bash"
    }
  }
}

POST /services/:service_code/:environment_name/instances/:id?operation=accessconsole

Access the console of an instance in a given environment with the specific ID.

For container type instances, the containerRemoteAccessCommand is required. For VM type instances, the vmRemoteAccessType is required.

Optional	Description	Default
containerRemoteAccessCommand string	The command to execute on the container instance. ex. /bin/bash	/bin/bash
vmRemoteAccessType VmRemoteAccessType	The remote access type. Can be either SERIAL or VNC. Invalid value will be ignored and the default will be used.	SERIAL

Network policy rules

Network policy rules allows you to control inbound and outbound traffic to your workload.

List network policy rules

curl -X GET \
  -H "MC-Api-Key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/networkpolicyrules"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "stackId": "bcc60174-50e6-44e4-bd45-463845124d87",
      "workloadId": "",
      "networkPolicyId": "f89e80ed-1208-4607-82b2-df2779d90f21",
      "id": "f89e80ed-1208-4607-82b2-df2779d90f21/701825869",
      "description": "Allow ICMP packets",
      "type": "INBOUND",
      "source": "0.0.0.0/0",
      "action": "INBOUND",
      "protocol": "ICMP",
      "portRange": ""
    },
    {
      "stackId": "bcc60174-50e6-44e4-bd45-463845124d87",
      "workloadId": "6ca53aff-8930-46d6-ba86-afbeb0b46bb7",
      "networkPolicyId": "2ac958f2-0976-4de9-95f6-3546fc10f8d0",
      "id": "2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0",
      "description": "custom-inbound",
      "type": "INBOUND",
      "source": "192.168.0.1/32",
      "action": "ALLOW",
      "protocol": "TCP",
      "portRange": "80"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/networkpolicyrules

Retrieve a list of all network policy rules in a given environment.

Query Params
workloadId string	The workload ID to get the network policy rules for. It is optional.
type string	The type of network policy rule, either INBOUND or OUTBOUND. It is optional.

Attributes
id string	The ID of the network policy rule, in the form networkProfileId/type/hashCode/occurrence.
stackId UUID	The UUID of the stack to which the network policy belongs.
workloadId UUID	The UUID of the workload to which the network policy rule is applied. Corresponds to the first workload ID in the network policy's list of instance selectors.
networkPolicyId UUID	The UUID of the network policy to which the network policy rule belongs.
description string	A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule.
type string	The type of network policy rule, either INBOUND or OUTBOUND.
source string	A subnet that will define all the IPs allowed or denied by this rule.
action string	The network policy rule action: ALLOW (allow traffic) or BLOCK (deny traffic).
protocol string	Supported protocols are: TCP, UDP, TCP_UDP, ESP, AH, ICMP or GRE.
portRange string	This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen.

Retrieve a network policy rule

curl -X GET \
  -H "MC-Api-Key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/networkpolicyrules/2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0"

The above command returns a JSON structured like this:

{
  "data": {
    "stackId": "bcc60174-50e6-44e4-bd45-463845124d87",
    "workloadId": "6ca53aff-8930-46d6-ba86-afbeb0b46bb7",
    "networkPolicyId": "2ac958f2-0976-4de9-95f6-3546fc10f8d0",
    "id": "2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0",
    "description": "custom-inbound",
    "type": "INBOUND",
    "source": "192.168.0.1/32",
    "action": "ALLOW",
    "protocol": "TCP",
    "portRange": "80"
  }
}

GET /services/:service_code/:environment_name/networkpolicyrules/:id

Retrieve a network policy rule in a given environment.

Attributes
id string	The ID of the network policy rule, in the form networkProfileId/type/hashCode/occurrence.
stackId UUID	The UUID of the stack to which the network policy belongs.
workloadId UUID	The UUID of the workload to which the network policy rule is applied. Corresponds to the first workload ID in the network policy's list of instance selectors.
networkPolicyId UUID	The UUID of the network policy to which the network policy rule belongs.
description string	A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule.
type string	The type of network policy rule, either INBOUND or OUTBOUND.
source string	A subnet that will define all the IPs allowed or denied by this rule.
action string	The network policy rule action: ALLOW (allow traffic) or BLOCK (deny traffic).
protocol string	Supported protocols are: TCP, UDP, TCP_UDP, ESP, AH, ICMP or GRE.
portRange string	This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen.

Create a network policy rule

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/networkpolicyrules"

Request body example:

{
  "workloadId": "bf9fd2ac-f761-46ef-88e0-b61ef68f8619",
  "description": "npr_cloudmc_isk",
  "protocol": "TCP",
  "type": "INBOUND",
  "action": "ALLOW",
  "source": "0.0.0.0/0",
  "portRange": "8080"
}

POST /services/:service_code/:environment_name/networkpolicyrules

Create a new network policy rule.

Required
workloadId UUID	The workload UUID to create a network policy for.
description string	A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule.
protocol string	Supported protocols are: TCP, UDP, TCP_UDP, ESP and AH.
type string	The type of network policy rule. Supported types are: INBOUND (Ingress) and OUTBOUND (Egress).
action string	The network policy rule action: ALLOW (allow traffic) or BLOCK (block traffic).
source string	A subnet that will define all the IPs allowed or denied by this rule.
portRange string	This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen.

Delete a network policy rule

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
  "https://cloudmc_endpoint/api/v1/services/stack/razine-test-env/networkpolicyrules/93cf3029-3657-44c4-add1-22c4ee2bcb94/INBOUND/1617554972/0"

DELETE /services/:service_code/:environment_name/networkpolicyrules/:id

Delete a network policy rule.

Edit a network policy rule

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/networkpolicyrules/2ac958f2-0976-4de9-95f6-3546fc10f8d0/INBOUND/-812331665/0"

Request body example:

{
  "description": "npr_cloudmc_isk",
  "workloadId": "6ca53aff-8930-46d6-ba86-afbeb0b46bb7",
  "type": "INBOUND",
  "source": "192.168.0.1/32",
  "action": "ALLOW",
  "protocol": "TCP",
  "portRange": "80"
}

PUT /services/:service_code/:environment_name/networkpolicyrules/:id

Edit a network policy rule.

Required
description string	A summary of what this rule does or a name of this rule. It is highly recommended to give a unique description to easily identify a rule.
workloadId UUID	The UUID of the workload to which the network policy rule is applied. Corresponds to the first workload ID in the network policy's list of instance selectors.
type string	The type of network policy rule. Supported types are: INBOUND (Ingress) and OUTBOUND (Egress).
source string	A CIDR subnet that will define all the IPs allowed or denied by this rule.
action string	The network policy rule action: ALLOW (allow traffic) or BLOCK (deny traffic).
protocol string	Supported protocols are: TCP, UDP, TCP_UDP, ESP or AH.
portRange string	This specifies on which ports traffic will be allowed or denied by this rule. It can be a range of ports separated by a hyphen. Not required for protocol for ESP or AH.

Edge delivery

Sites

Create and manage your CDN, WAF, and/or Serverless Scripting Delivery sites.

List sites

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
      "domain": "slow-test.com",
      "createdAt": "2021-02-19T19:29:58.713874Z",
      "updatedAt": "2021-02-19T19:30:04.656652Z",
      "services": [
        "CDN",
        "SERVERLESS_EDGE_ENGINE",
        "WAF"
      ],
      "id": "9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5",
      "status": "ACTIVE"
    },
    {
      "stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
      "domain": "speedytest.com",
      "createdAt": "2021-02-08T14:57:01.576395Z",
      "updatedAt": "2021-02-08T14:57:09.861832Z",
      "services": [
        "CDN",
        "WAF"
      ],
      "id": "04deb6d1-ad84-425f-8f10-92106a22c3b4",
      "status": "ACTIVE"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/sites

Retrieve a list of all sites in a given environment.

Optional
status string	Setting the status parameter will return only the stackpath sites with that particular status. The site's status can either be ACTIVE, PENDING, or PROVISIONING.

Attributes
id string	A sites's unique identifier.
stackId string	The ID of the stack that a site belongs to.
domain string	The domain of the site.
status string	The status of the site. It can either be ACTIVE, PENDING, or PROVISIONING.
createdAt string	The date on which the site was created.
updatedAt string	The date on which the site was last updated.
services array	List of services running on the site.

Retrieve a site

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5"

The above command returns a JSON structured like this:

{
  "data": {
    "stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
    "domain": "slow-test.com",
    "createdAt": "2021-02-19T19:29:58.713874Z",
    "updatedAt": "2021-02-19T19:30:04.656652Z",
    "services": [
      "CDN",
      "SERVERLESS_EDGE_ENGINE",
      "WAF"
    ],
    "id": "9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5",
    "status": "ACTIVE",
    "edgeAddress": "v2a4k7y8.stackpathcdn.com",
    "anycastIp": "151.139.128.10",
    "deliveryDomains": [
    {
      "domain": "v2a4k7y8.stackpathcdn.com",
      "validatedAt": "2021-02-26T19:00:15.177411Z"
    },
    {
      "domain": "slow-test.com",
    }],
  }
}

GET /services/:service_code/:environment_name/sites/:id

Retrieve a site in a given environment.

Attributes
id string	A sites's unique identifier.
stackId string	The ID of the stack that a site belongs to.
domain string	The domain of the site.
status string	The status of the site. It can either be ACTIVE, PENDING, or PROVISIONING.
createdAt string	The date on which the site was created.
updatedAt string	The date on which the site was last updated.
services array	List of services running on the site.
edgeAddress string	The edge address of the site.
anycastIp string	The Anycast IP address that domains should be pointed to.
deliveryDomains array	List of delivery domains of the site.
deliveryDomains.domain string	A delivery domain of the site.
deliveryDomains.validatedAt string	The date the domain was validated to be pointing to Stackpath.

Create a site

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites"

Request body example for a site with basic authentication:

{
  "domain": "www.rpgfan.com",
  "services": [
    "CDN",
    "SERVERLESS_EDGE_ENGINE",
    "WAF"
  ],
  "protocol": "HTTPS",
  "hostname": "199.250.204.212",
  "authMethod": "BASIC",
  "username": "alavoie",
  "password": "123456"
}

Request body example for a site with no authentication:

{
  "domain": "www.rpgfan.com",
  "services": [
    "CDN",
    "SERVERLESS_EDGE_ENGINE",
    "WAF"
  ],
  "protocol": "HTTPS",
  "hostname": "199.250.204.212"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/sites

Create a site in a given environment.

Required
domain string	The domain name that will be used for the site.
services Array[string]	Services list that will be used on the site. Possibles values are CDN,SERVERLESS_EDGE_ENGINE or WAF.
protocol string	Protocol that will be used to communicate with the hostname. Possibles values are HTTP or HTTPS.
hostname string	The hostname to that will be used to get the information from. The hostname can be an IP or a name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test).

Optional
authMethod string	The authentication method to communicate with the hostname. Possibles values are NONE or BASIC. If not provided, it will default to NONE unless the username or password is provided. It would then default to BASIC.
username Array[Object]	The username for the basic authentication. Required if authMethod is BASIC or if the password id provided.
password string	The password for the basic authentication. Required if authMethod is BASIC or if the password id provided.

Delete a site

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/sites/:id

Delete a site in a given environment.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Enable CDN

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=enable_cdn"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/sites/:id?operation=enable_cdn

Enable CDN for a given site.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Disable CDN

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=disable_cdn"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/sites/:id?operation=disable_cdn

Disable CDN for a given site.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Enable WAF

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=enable_waf"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/sites/:id?operation=enable_waf

Enable WAF for a given site.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Disable WAF

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=disable_waf"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/sites/:id?operation=disable_waf

Disable WAF for a given site.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Enable Serverless Scripts

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=enable_scripts"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/sites/:id?operation=enable_scripts

Enable Serverless Scripts for a given site.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Disable Serverless Scripts

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/sites/f8ad8351-4f07-4b52-92ec-fd2983873853?operation=disable_scripts"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/sites/:id?operation=disable_scripts

Disable Serverless Scripts for a given site.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Origin Settings

Retrieve origin settings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/originsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
    "stackId": "144c3d16-2879-4286-82b6-75e58a6ec1cb",
    "scopeConfigurationId": "45ab2429-ca8d-4145-acc3-f6aea6e8dbef",
    "domain": "bluegreen.com",
    "webSocketsEnabled": false,
    "sslValidationEnabled": false,
    "pullProtocol": "MATCH",
    "hostHeader": "Host: marvel.com",
    "origin": {
      "id": "d92531f4-28f5-456d-9b5f-d1cbb17ccfee",
      "address": "www.test.com:80",
      "commonCertificateName": "commonName", 
      "authMethod": "BASIC", 
      "username": "username"
    },
    "backupOriginEnabled": true,
    "backupOriginExcludeCodes": ["415"],
    "backupOrigin": {
      "id": "f6766ee9-680d-4c92-b77c-36c60a251061",
      "address": "1.2.3.4:443/path",
      "authMethod": "NONE"
    }
  }
}

GET /services/:service_code/:environment_name/originsettings/:id

Retrieve origin settings for a site in a given environment.

Attributes
id UUID	A site's unique identifier.
stackId UUID	The ID of the stack that a site belongs to.
scopeConfigurationId UUID	The ID of the scope of the site that the origins are connected to.
domain string	The domain of the site.
webSocketsEnabled boolean	Specifies if web socket connections to the origin server are enabled.
sslValidationEnabled boolean	Specifies if SSL validation for the origins is enabled.
pullProtocol string	The type of protocol used to pull content from the origin. Must be one of ["HTTP", "HTTPS", "MATCH"]. "MATCH" is equivalent to "HTTP or HTTPS".
hostHeader string	The host header to be used to pull content from the origin. "Dynamic" refers to using the requested domain name (Host: %client.request.host%) as the host header.
origin Object	The primary origin that the CDN uses to pull content from.
origin.id UUID	An origin's unique identifier.
origin.address string	The address of the primary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091].
origin.authMethod string	Specifies the authentication method that the origin uses. Must be one of ["NONE", "BASIC"].
origin.username string	Username to use when authenticating with the origin.
origin.password string	Password to use when authenticating with the origin.
origin.commonCertificateName string	Common name to validate SSL origin requests against.
backupOriginEnabled boolean	Specifies if a backup origin for the site is configured.
backupOriginExcludeCodes Array[string]	Requests are made to the backup origin on any 4xx or 5xx response codes returned from the primary origin. This property specifies the response status codes for which calls to the backup origin must not be made. Multiple response codes can be excluded. e.g: ["410", "411", "412"]. Asterisks can be used to cover a range of codes. e.g. All the 4xx codes can be covered using "4*".
backupOrigin Object	The secondary origin that the CDN uses to pull content from when the primary origin is not available.
backupOrigin.id UUID	A backup origin's unique identifier.
backupOrigin.address string	The address of the secondary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091].
backupOrigin.authMethod string	Specifies the authentication method that the backup origin uses. Must be one of ["NONE", "BASIC"].
backupOrigin.username string	Username to use when authenticating with the backup origin.
backupOrigin.password string	Password to use when authenticating with the backup origin.
backupOrigin.commonCertificateName string	Common name to validate SSL origin requests against.

Edit origin settings

curl -X PATCH \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/originsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"

Request body example:

{
  "pullProtocol": "MATCH",
  "hostHeader": "marvel.com",
  "sslValidationEnabled": true, 
  "origin": {
    "commonCertificateName": "commonName"
  }, 
  "backupOriginEnabled": true, 
  "backupOrigin": {
    "address": "1.2.3.4:80"
  }
}

The above command returns a JSON structured like this:

{
  "taskId": "e94d2bb6-059a-4eb6-a14f-7c596a5fdea6",
  "taskStatus": "SUCCESS"
}

PATCH /services/:service_code/:environment_name/originsettings/:id

Edit origin settings for a site in a given environment.

Optional
webSocketsEnabled boolean	Specifies if web socket connections to the origin server are enabled.
sslValidationEnabled boolean	Specifies if SSL validation for the origins is enabled.
pullProtocol string	The type of protocol used to pull content from the origin. Must be one of ["HTTP", "HTTPS", "MATCH"]. "MATCH" is equivalent to "HTTP or HTTPS".
hostHeader string	The host header to be used to pull content from the origin. "Dynamic" refers to using the requested domain name (Host: %client.request.host%) as the host header.
origin Object	The primary origin that the CDN uses to pull content from.
origin.address string	The address of the primary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091].
origin.authMethod string	Specifies the authentication method that the origin uses. Must be one of ["NONE", "BASIC"].
origin.username string	Username to use when authenticating with the origin.
origin.password string	Password to use when authenticating with the origin.
origin.commonCertificateName string	Common name to validate SSL origin requests against.
backupOriginEnabled boolean	Specifies if a backup origin for the site is configured. To configure backupOrigin's settings, this property must be passed as true.
backupOriginExcludeCodes Array[string]	Requests are made to the backup origin on any 4xx or 5xx response codes returned from the primary origin. This property specifies the response status codes for which calls to the backup origin must not be made. Multiple response codes can be excluded. e.g: ["410", "411", "412"]. Asterisks can be used to cover a range of codes. e.g. All the 4xx codes can be covered using "4*".
backupOrigin Object	The secondary origin that the CDN uses to pull content from when the primary origin is not available.
backupOrigin.address string	The address of the secondary origin that the CDN uses to pull content from. Can be a valid IPv4 address or a valid domain name. It may include a specific port and a precise path as well (e.g. 199.250.204.212:80/test). Port must be one of [80, 8080, 443, 1935, 9091].
backupOrigin.authMethod string	Specifies the authentication method that the backup origin uses. Must be one of ["NONE", "BASIC"].
backupOrigin.username string	Username to use when authenticating with the backup origin.
backupOrigin.password string	Password to use when authenticating with the backup origin.
backupOrigin.commonCertificateName string	Common name to validate SSL origin requests against.

Delivery domains

Delivery domains allow the CDN to recognize an HTTP request and associate it with a site.

List delivery domains

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliverydomains?siteId=439b145a-7c55-4a73-8cf2-d8faabfe6d22"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com",
      "stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
      "siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
      "domain": "test-domain.com"
    },
    {
      "id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/u7f7rXXX.stackpathcdn.com",
      "stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
      "siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
      "domain": "u7f7rXXX.stackpathcdn.com",
      "validatedAt": "2021-02-26T19:00:15.177411Z"
    },
    {
      "id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/www.test-domain.com",
      "stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
      "siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
      "domain": "www.test-domain.com"
    }
  ],
  "metadata": {
    "recordCount": 3
  }
}

GET /services/:service_code/:environment_name/deliverydomains?siteId=:siteId

Retrieve a list of all delivery domains in a given environment for a site.

Query Params
siteId UUID	The ID of the site for which to list delivery domains. This parameter is required.

Attributes
id string	The delivery domain unique identifier.
domain string	The site's domain name.
siteId UUID	The ID of the site that the delivery domain belongs to.
stackId UUID	The ID of the stack that the site belongs to.
updatedAt string	The date the domain was validated to be pointing to Stackpath.

Retrieve a delivery domain

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliverydomains/439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com",
    "stackId": "3deddcbd-3757-44cf-a4a6-93028fc4649a",
    "siteId": "439b145a-7c55-4a73-8cf2-d8faabfe6d22",
    "domain": "test-domain.com"
  }
}

GET /services/:service_code/:environment_name/deliverydomains/:id

Retrieve a delivery domain of a site in a given environment.

Attributes
id string	The delivery domain unique identifier.
domain string	The site's domain name.
siteId UUID	The ID of the site that the delivery domain belongs to.
stackId UUID	The ID of the stack that the site belongs to.
updatedAt string	The date the domain was validated to be pointing to Stackpath.

Delete a delivery domain

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliverydomains/439b145a-7c55-4a73-8cf2-d8faabfe6d22/test-domain.com"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/deliverydomains/:id

Delete a delivery domain of a site in a given environment.

Attributes
taskId string	The task id related to the site deletion.
taskStatus string	The status of the operation.

Create a delivery domain

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliverydomains?siteId=a2fefb15-7e31-4c72-87e0-5a892e91c8d9"

Request body example:

{
  "domain": "new-domain.com",
}

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/deliverydomains?siteId=:id

Create a delivery domain of a site in a given environment.

Required
domain string	The site's domain name.

Attributes
taskId string	The task id related to the domain creation.
taskStatus string	The status of the operation.

CDN

Retrieve CDN settings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b"

The above command returns a JSON structured like this:

{
  "data": {
    "siteId": "9f236f19-55db-411f-9f05-bd79dc91a69b",
    "cacheExpirePolicy": "SPECIFY_CDN_TTL",
    "cacheTtl": 60,
    "queryStringControl": "CUSTOM",
    "customCachedQueryStrings": [
      "customQuery",
    ],
    "dynamicCachingByHeaderEnabled": true,
    "customCachedHeaders": [
      "mydynamicheader"
    ],
    "gzipCompressionEnabled": true,
    "gzipCompressionLevel": 2,
    "contentPersistenceEnabled": true,
    "maximumStaleFileTtl": 30,
    "varyHeaderEnabled": true,
    "browserCacheTtl": 60,
    "corsHeaderEnabled": true,
    "allowedCorsOrigins": "SPECIFY_ORIGINS",
    "originsToAllowCors": [
      "example.org"
    ],
    "http2SupportEnabled": true,
    "http2ServerPushEnabled": true,
    "linkHeader": "my-link-header",
    "canonicalHeaderEnabled": true,
    "canonicalHeader": "my-canonical-header",
    "urlCachingEnabled": true,
    "urlCachingTtl": 300
  }
}

GET /services/:service_code/:environment_name/cdnsettings/:siteId

Retrieve CDN settings for a site in a given environment.

Attributes
siteId UUID	A site's unique identifier.
cacheExpirePolicy String	A site's cache expiry policy. Can be ORIGIN_CONTROLLED, SPECIFY_CDN_TTL, NEVER_EXPIRE, or DO_NOT_CACHE.
cacheTtl Integer	The time to live for the cache, in seconds. Depends on the cache expiry policy.
queryStringControl String	The strategy for caching query strings. Can be IGNORE, CACHE_ALL or CUSTOM.
customCachedQueryStrings Array[String]	List of custom cached query strings. Only visible if the queryStringControl attribute is CUSTOM.
dynamicCachingByHeaderEnabled Boolean	Whether or not to enable dynamic caching by headers.
customCachedHeaders Array[String]	A list of custom cached headers. Only visible if dynamicCachingByHeaderEnabled is true.
gzipCompressionEnabled Boolean	Whether or not to enable gzip compression.
gzipCompressionLevel Integer	The level for the gzip compression. Values are between 1 to 6. Only visible is gzipCompressionEnabled is true.
contentPersistenceEnabled Boolean	Whether or not make cached content available after its expiration time.
maximumStaleFileTtl Integer	The maximum time to live for stale files, in seconds. Only visible if contentPersistenceEnabled is true.
varyHeaderEnabled Boolean	Whether or not to enable honoring the vary header in a request.
browserCacheTtl Integer	Sets the default browser expiration time for cached assets, in seconds.
corsHeaderEnabled Boolean	Sets the Access-Control-Allow-Origin header to allow browsers to access this domain from other origins.
allowedCorsOrigins String	The strategy for allowing cors origins. Can be SPECIFY_ORIGINS or ALL_ORIGINS.
originsToAllowCors Array[String]	A list of origins to allow cors requests from. Only visible if allowedCorsOrigins is set to SPECIFY_ORIGINS.
http2SupportEnabled Boolean	Whether or not to enable supporting applications using HTTP/2 protocol.
http2ServerPushEnabled Boolean	Whether or not to push assets to the client or browser (user) in advance (before the user requests these assets) which enables faster load times.
linkHeader String	The link header for http2ServerPush, only visible if http2ServerPushEnabled is true.
canonicalHeaderEnabled Boolean	Whether or not to enable setting Link: http://{hostname}/URI; rel="canonical" header on each response.
canonicalHeader String	The hostname for the canonicalHeader, only visible if canonicalHeaderEnabled is true.
urlCachingEnabled Boolean	Whether or not to enable caching of URLs without file extensions.
urlCachingTtl Integer	The time to live for the url cache. Only visible if urlCachingEnabled is true.

Edit CDN settings

curl -X PATCH \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b"

Request body example:

{
  "urlCachingEnabled": true,
  "urlCachingTtl": 1,
  "canonicalHeaderEnabled": true,
  "queryStringControl": "CUSTOM",
  "customCachedQueryStrings": [
    "help"
  ]
}

The above command returns a JSON structured like this:

{
  "taskId": "e94d2bb6-059a-4eb6-a14f-7c596a5fdea6",
  "taskStatus": "SUCCESS"
}

PATCH /services/:service_code/:environment_name/cdnsettings/:siteId

Edit CDN settings for a site in a given environment.

Optional
cacheExpirePolicy String	A site's cache expiry policy. Can be ORIGIN_CONTROLLED, SPECIFY_CDN_TTL, NEVER_EXPIRE, or DO_NOT_CACHE.
cacheTtl Integer	The time to live for the cache, in seconds. Only applies when attribute cacheExpirePolicy is SPECIFY_CDN_TTL.
queryStringControl String	The strategy for caching query strings. Can be IGNORE, CACHE_ALL or CUSTOM.
customCachedQueryStrings Array[String]	List of custom cached query strings. Only applies when attribute queryStringControl is CUSTOM.
dynamicCachingByHeaderEnabled Boolean	Whether or not to enable dynamic caching by headers.
customCachedHeaders Array[String]	A list of custom cached headers. Only applies when attribute dynamicCachingByHeaderEnabled is true.
gzipCompressionEnabled Boolean	Whether or not to enable gzip compression.
gzipCompressionLevel Integer	The level for the gzip compression. Values should be between 1 to 6, where 6 is the default. Only applies when attribute gzipCompressionEnabled is true.
contentPersistenceEnabled Boolean	Whether or not make cached content available after its expiration time.
maximumStaleFileTtl Integer	The maximum time to live for stale files, in seconds. Only applies when attribute contentPersistenceEnabled is true.
varyHeaderEnabled Boolean	Whether or not to enable honoring the vary header in a request.
browserCacheTtl Integer	Sets the default browser expiration time for cached assets, in seconds.
corsHeaderEnabled Boolean	Sets the Access-Control-Allow-Origin header to allow browsers to access this domain from other origins.
allowedCorsOrigins String	The strategy for allowing cors origins. Can be SPECIFY_ORIGINS or ALL_ORIGINS.
originsToAllowCors Array[String]	A list of origins to allow cors requests from. Only applies when attribute allowedCorsOrigins is set to SPECIFY_ORIGINS.
http2SupportEnabled Boolean	Whether or not to enable supporting applications using HTTP/2 protocol.
http2ServerPushEnabled Boolean	Whether or not to push assets to the client or browser (user) in advance (before the user requests these assets) which enables faster load times.
linkHeader String	The link header for http2ServerPush, only visible if http2ServerPushEnabled is true.
canonicalHeaderEnabled Boolean	Whether or not to enable setting Link: http://{hostname}/URI; rel="canonical" header on each response.
canonicalHeader String	The hostname for the canonicalHeader, only applies when attribute canonicalHeaderEnabled is true.
urlCachingEnabled Boolean	Whether or not to enable caching of URLs without file extensions.
urlCachingTtl Integer	The time to live for the url cache. Only applies when attribute urlCachingEnabled is true.

Purge all CDN cached content

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b?operation=purgeAll"

The above command returns a JSON structured like this:

{
  "taskId": "e6c03893-212f-4e28-b7a1-66ed7b554839",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/cdnsettings/:siteId?operation=purgeAll

Purge all CDN cached content of a site in a given environment.

Attributes
taskId string	The task id related to the purge operation.
taskStatus string	The status of the operation.

Purge custom CDN cached content

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/cdnsettings/9f236f19-55db-411f-9f05-bd79dc91a69b?operation=purge"

Request body example for URL purge type:

{
  "purgeType":"URL",
  "items": [
    {
      "url": "http://<domain-name>",
      "recursive": true,
      "purgeAllDynamic": true,
      "headers": [],
      "purgeSelector": {
        "selectorName": "(?i)<header_name>",
        "selectorValue": "<header_value>",
        "selectorType": "HEADER",
        "selectorValueDelimiter": ""
      }
    }
  ]
}

Request body example for PATH purge type:

{
  "purgeType":"PATH",
  "items": [
    {
      "url": "/path/to/file",
      "recursive": false,
      "purgeAllDynamic": false,
      "headers": [],
      "purgeSelector": {
        "selectorName": "(?i)<header_name>",
        "selectorValue": "<header_value>",
        "selectorType": "HEADER",
        "selectorValueDelimiter": ""
      }
    }
  ]
}

The above command returns a JSON structured like this:

{
  "taskId": "e6c03893-212f-4e28-b7a1-66ed7b554839",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/cdnsettings/:siteId?operation=purge

Purge custom CDN cached content of a site in a given environment.

Required
items Array[Object]	The items to purge from the CDN.
items.url String	The URL or path at which to delete content.

Optional
purgeType String	The type of cache purge. Can be URL or PATH. Default value is URL.
items.recursive Boolean	Whether or not to recursively delete content from the CDN.
items.invalidateOnly Boolean	Whether or not to mark the asset as expired and re-validate instead of deleting.
items.purgeAllDynamic Boolean	Whether or not to purge dynamic versions of assets.
items.headers Array[String]	A list of HTTP request headers used to construct a cache key to purge content by. These headers must be configured in the site configuration's DynamicContent.headerFields property.
items.purgeSelector Array[Object]	A key/value pair definition of content to purge from the CDN.
items.purgeSelector.selectorType String	The kinds of content that can be purged from the CDN. One of: HEADER (Purge content based on an HTTP response header), TAG (Purge content based on an X-TAG HTTP header value. Purging by tag can be useful when content on the origin is tagged).
items.purgeSelector.selectorName String	The name of the type of content to purge. For example, the name of the HTTP response header. Names are case sensitive.
items.purgeSelector.selectorValue String	The value of the content to purge. For example, the value of the HTTP response header. Values are case sensitive and may be wild-carded, but cannot match a "/".
items.purgeSelector.selectorValueDelimiter String	The delimiter to separate multiple values with. Defaults to ",".

WAF

Retrieve WAF Settings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/wafsettings/1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36",
    "stackId": "1415650d-1d02-4097-a79a-8f6e4bb4f483",
    "domain": "site.com",
    "apiUrls": [
      "/test/this/way"
    ],
    "ddosSettings": {
      "globalThreshold": 5000,
      "burstThreshold": 110,
      "subSecondBurstThreshold": 50
    },
    "monitoringEnabled": false,
    "owaspThreats": {
      "sqlInjection": false,
      "xssAttack": true,
      "remoteFileInclusion": true,
      "wordpressWafRuleset": true,
      "apacheStrutsExploit": true,
      "localFileInclusion": false,
      "commonWebApplicationVulnerabilities": true,
      "webShellExecutionAttempt": true,
      "responseHeaderInjection": true,
      "openRedirect": false,
      "shellInjection": false
    },
    "userAgents": {
      "blockInvalidUserAgents": false,
      "blockUnknownUserAgents": true
    },
    "csrf": true,
    "trafficSources": {
      "viaTorNodes": true,
      "viaProxyNetworks": true,
      "viaHostingServices": true,
      "viaVpn": true,
      "convictedBotTraffic": true,
      "suspiciousTrafficByLocalIpFormat": true
    },
    "antiAutomationBotProtection": {
      "forceBrowserValidationOnTrafficAnomalies": true,
      "challengeAutomatedClients": false,
      "challengeHeadlessBrowsers": false,
      "antiScraping": false
    },
    "spamAndAbuseForm": false,
    "behavioralWaf": {
      "spamProtection": true,
      "blockProbingAndForcedBrowsing": true,
      "obfuscatedAttacksAndZeroDayMitigation": true,
      "repeatedViolations": true,
      "bruteForceProtection": true
    },
    "cmsProtection": {
      "whiteListWordpress": false,
      "whiteListModx": false,
      "whiteListDrupal": false,
      "whiteListJoomla": false,
      "whiteMagento": false,
      "whiteListOriginIp": true,
      "whiteListUmbraco": false
    },
    "allowKnownBots": {
      "Internet Archive Bot": true,
    }
  }
}

GET /services/:service_code/:environment_name/wafsettings/:siteId

Retrieve WAF Settings for a site in a given environment.

Attributes
id string	The ID of the site that the WAF settings belongs to.
stackId string	The ID of the stack that a site belongs to.
domain string	The domain of the site.
ddosSettings object	The DDoS Setting containing the different threshold values.
ddosSettings.globalThreshold Integer	The number of overall requests per ten seconds that can trigger DDoS protection.
ddosSettings.burstThreshold Integer	The number of requests per two seconds that can trigger DDoS protection.
ddosSettings.subSecondBurstThreshold Integer	The number of requests per 0.1 seconds that can trigger DDoS protection.
apiUrls array	List of configured API urls.
monitoringEnabled boolean	If the monitoring mode is enabled.
owaspThreats object	StackPath’s core rule set & OWASP’s most critical Web application security risks.
owaspThreats.sqlInjection boolean	Block requests suspected of being a SQL injection attack attempt. SQL injection attacks attempt to exploit vulnerabilities in a Web application's code and seek to gain access and control over the database. A successful attack would typically result in stolen data or the site being defaced or taken down.
owaspThreats.xssAttack boolean	Block requests suspected of being a Cross-Site-Scripting attack attempt. Cross Site Scripting attacks attempt to exploit vulnerabilities in a Web application and seek to inject a client side script either across an entire site or to a specific user's session. A successful attack would typically allow forbidden access to a user's actions and data.
owaspThreats.shellShockAttack boolean	Block requests suspected of being a Shellshock attack attempt. A Shellshock attack is an attempt to exploit a server's vulnerabilities to gain full access and control over them. A successful attack would typically either abuse a server's resources or hack the website.
owaspThreats.remoteFileInclusion boolean	Block requests suspected of being a Remote File Inclusion attempt. Remote File Inclusion attempts to exploit vulnerabilities in a Web application (typically in PHP) to execute a script from a 3rd party server. RFI attacks provide a backdoor for the hacker to change the behaviour of a server and Web application.
owaspThreats.wordpressWafRuleset boolean	Enable a set of rules designed to block common Wordpress exploits.
owaspThreats.apacheStrutsExploit boolean	Patch known vulnerabilities in the Apache Struts framework by blocking requests suspected of exploiting these vulnerabilities.
owaspThreats.localFileInclusion boolean	Block requests suspected of a Local File Inclusion attempt. Local File Inclusion attempts seek to exploit vulnerabilities in a Web application to execute potentially harmful scripts on your servers.
owaspThreats.commonWebApplicationVulnerabilities boolean	Block attempts to access and potentially harm your servers through common backdoors, such as common control panels, configuration scripts etc. which may be accessible to unwanted users.
owaspThreats.webShellExecutionAttempt boolean	Block requests suspected of Web shell attempts. A Web shell is a script that can be uploaded to a Web server to enable remote administration of the machine. Infected Web servers can either be internet-facing or internal to the network, where the Web shell is used to further pivot to internal hosts.
owaspThreats.responseHeaderInjection boolean	Block requests suspected of Response header injection attempts. Response header injection attempts to inject a header via insufficient user input sanitation.
owaspThreats.openRedirect boolean	Block requests suspected of being an Open Redirect attempt. Open Redirect attempts to exploit vulnerabilities in a Web application to redirect a user to a new website without any validation of the target of redirect.
owaspThreats.shellInjection boolean	Block requests suspected of being a shell injection attack attempt. Shell Injection is an attack in which the goal is execution of arbitrary commands on the host operating system via a vulnerable application. Command injection attacks are possible when an application passes unsafe user supplied data (forms, cookies, HTTP headers etc.) to a system shell.
userAgents object	Block requests with missing or invalid user agent string.
userAgents.blockInvalidUserAgents boolean	Block requests in which the HTTP header describing the user-agent (browser and platform) seems invalid and cannot be translated to a known legitimate browser. Automated processes (bots) are most likely to have invalid user agents.
userAgents.blockUnknownUserAgents boolean	Block requests in which the HTTP header describing the user-agent (browser and platform) is missing.
csrf boolean	StackPath WAF will generate a CSRF token that is added to forms. Requests without a valid CSRF token will be blocked.
trafficSources object	Real-time threat intelligence for IP addresses, source location, and information on malicious IPs.
trafficSources.viaTorNodes boolean	Challenge traffic from The Onion Ring exit nodes to block bots and known bad devices. While TOR is used sometimes purely for Web anonymity, it is commonly used by hackers, scrapers, and spammers to crawl or hack Web applications.
trafficSources.viaProxyNetworks boolean	Challenge traffic from any known proxy network to block bots and known bad devices. While proxy services are used sometimes purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications.
trafficSources.viaHostingServices boolean	Challenge traffic from IP addresses known to be of hosting service companies. This rule is unlikely to see legitimate human traffic on these IP spaces since they are typically used for server hosting. In most cases, traffic from these IP spaces originate from infected servers that are controlled by hackers.
trafficSources.viaVpn boolean	Challenge traffic from any known VPN to block bots and known bad devices. While VPNs are sometimes used purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications.
trafficSources.convictedBotTraffic boolean	Challenge traffic from IP addresses that have been convicted of automated activities (bots) on this site or on others. These IP addresses are used by malicious automated agents while no legitimate traffic has been observed on them.
trafficSources.suspiciousTrafficByLocalIpFormat boolean	Challenge traffic from suspicious NAT ranges.
antiAutomationBotProtection object	Block automated traffic from scanning and browsing your online application.
antiAutomationBotProtection.forceBrowserValidationOnTrafficAnomalies boolean	Challenge and block requests if the user or device behind them does not keep session cookies and does not execute JavaScripts correctly. Most malicious automated activities (bots) do not meet these conditions and will, therefore, effectively be blocked by the JavaScript challenge triggered in any suspected situation. Clients can also be blocked depending on whether they act in an abnormal to the specific domain—by scraping content in a way that most sessions on this domain don't—or clients that try to, for example, avoid detection by switching IPs.
antiAutomationBotProtection.challengeAutomatedClients boolean	Captcha-challenge and block sessions conducted by standard Web browsers if there is evidence that these sessions are being automated and not driven by a human user. Such automation is used primarily for screen scraping and other very targeted, site-specific malicious automation.
antiAutomationBotProtection.challengeHeadlessBrowsers boolean	Challenge requests if the user or device behind them uses an automation tool that initiates browsers but is actually an automation tool without real display—such as phantomJS, Selenium, or other. While such tools are favored by programmers, they are also extremely popular with scrapers, hackers and even in sophisticated DDoS attacks to circumvent standard anti-bot measures.
antiAutomationBotProtection.antiScraping boolean	A more hardened anti-automation policy that is meant to stop scrapers by using faster and harsher convictions.
spamAndAbuseForm boolean	Challenge and prevent automated tools from making HTTP/S Post requests without validating their session first.
cmsProtection object	Whitelist admin users.
cmsProtection.whiteListWordpress boolean	Enable whitelist WordPress admin logged-in users.
cmsProtection.whiteListModx boolean	Enable whitelist MODX admin logged-in users.
cmsProtection.whiteListDrupal boolean	Enable whitelist Drupal admin logged-in users.
cmsProtection.whiteListJoomla boolean	Enable whitelist Joomla admin logged-in users.
cmsProtection.whiteMagento boolean	Enable whitelist Magento admin logged-in users.
cmsProtection.whiteListOriginIp boolean	Enable this policy to whitelist requests coming from the origin for plugin updates and general CMS updates,
cmsProtection.whiteListUmbraco boolean	Enable whitelist Umbraco admin logged-in users.
behavioralWaf object	StackPath's sophisticated user behaviour and reputation analysis rules.
behavioralWaf.spamProtection boolean	Challenge and block user sessions and activities that seem to be aggressively using forms on your website to post spam content, generate new accounts, and more. Also, require a handshake (if not already provided) to clients making POST requests.
behavioralWaf.blockProbingAndForcedBrowsing boolean	Challenge or block sessions and users that seem to make brute-forced requests on random URLs seeking to discover a Web application's structure and hidden directories.
behavioralWaf.obfuscatedAttacksAndZeroDayMitigation boolean	Block clients performing multiple injection attacks.
behavioralWaf.repeatedViolations boolean	Challenge or block clients that failed to answer previous challenges.
behavioralWaf.bruteForceProtection boolean	Challenge and block attempts seeking to guess user names and passwords on Web login forms.
allowKnownBots object	An object containing known bots.

Edit WAF Settings

curl -X PATCH \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/wafsettings/c0ddc1b3-b390-4f39-b200-5c0323ca306e"

Request body example:

{
    "owaspThreats": {
      "localFileInclusion": false
    }
}

The above command returns a JSON structured like this:

{
  "taskId": "573ca8fa-c5ad-4b19-a315-8ddbbc78d7c0",
  "taskStatus": "SUCCESS"
}

PATCH /services/:service_code/:environment_name/wafsettings/:siteId

Edit the WAF settings for a site in a given environment.

Attributes
ddosSettings object	The DDoS Setting containing the different threshold values.
ddosSettings.globalThreshold Integer	The number of overall requests per ten seconds that can trigger DDoS protection.
ddosSettings.burstThreshold Integer	The number of requests per two seconds that can trigger DDoS protection.
ddosSettings.subSecondBurstThreshold Integer	The number of requests per 0.1 seconds that can trigger DDoS protection.
apiUrls array	List of configured API urls.
monitoringEnabled boolean	If the monitoring mode is enabled.
owaspThreats object	StackPath’s core rule set & OWASP’s most critical Web application security risks.
owaspThreats.sqlInjection boolean	Block requests suspected of being a SQL injection attack attempt. SQL injection attacks attempt to exploit vulnerabilities in a Web application's code and seek to gain access and control over the database. A successful attack would typically result in stolen data or the site being defaced or taken down.
owaspThreats.xssAttack boolean	Block requests suspected of being a Cross-Site-Scripting attack attempt. Cross Site Scripting attacks attempt to exploit vulnerabilities in a Web application and seek to inject a client side script either across an entire site or to a specific user's session. A successful attack would typically allow forbidden access to a user's actions and data.
owaspThreats.shellShockAttack boolean	Block requests suspected of being a Shellshock attack attempt. A Shellshock attack is an attempt to exploit a server's vulnerabilities to gain full access and control over them. A successful attack would typically either abuse a server's resources or hack the website.
owaspThreats.remoteFileInclusion boolean	Block requests suspected of being a Remote File Inclusion attempt. Remote File Inclusion attempts to exploit vulnerabilities in a Web application (typically in PHP) to execute a script from a 3rd party server. RFI attacks provide a backdoor for the hacker to change the behaviour of a server and Web application.
owaspThreats.wordpressWafRuleset boolean	Enable a set of rules designed to block common Wordpress exploits.
owaspThreats.apacheStrutsExploit boolean	Patch known vulnerabilities in the Apache Struts framework by blocking requests suspected of exploiting these vulnerabilities.
owaspThreats.localFileInclusion boolean	Block requests suspected of a Local File Inclusion attempt. Local File Inclusion attempts seek to exploit vulnerabilities in a Web application to execute potentially harmful scripts on your servers.
owaspThreats.commonWebApplicationVulnerabilities boolean	Block attempts to access and potentially harm your servers through common backdoors, such as common control panels, configuration scripts etc. which may be accessible to unwanted users.
owaspThreats.webShellExecutionAttempt boolean	Block requests suspected of Web shell attempts. A Web shell is a script that can be uploaded to a Web server to enable remote administration of the machine. Infected Web servers can either be internet-facing or internal to the network, where the Web shell is used to further pivot to internal hosts.
owaspThreats.responseHeaderInjection boolean	Block requests suspected of Response header injection attempts. Response header injection attempts to inject a header via insufficient user input sanitation.
owaspThreats.openRedirect boolean	Block requests suspected of being an Open Redirect attempt. Open Redirect attempts to exploit vulnerabilities in a Web application to redirect a user to a new website without any validation of the target of redirect.
owaspThreats.shellInjection boolean	Block requests suspected of being a shell injection attack attempt. Shell Injection is an attack in which the goal is execution of arbitrary commands on the host operating system via a vulnerable application. Command injection attacks are possible when an application passes unsafe user supplied data (forms, cookies, HTTP headers etc.) to a system shell.
userAgents object	Block requests with missing or invalid user agent string.
userAgents.blockInvalidUserAgents boolean	Block requests in which the HTTP header describing the user-agent (browser and platform) seems invalid and cannot be translated to a known legitimate browser. Automated processes (bots) are most likely to have invalid user agents.
userAgents.blockUnknownUserAgents boolean	Block requests in which the HTTP header describing the user-agent (browser and platform) is missing.
csrf boolean	StackPath WAF will generate a CSRF token that is added to forms. Requests without a valid CSRF token will be blocked.
trafficSources object	Real-time threat intelligence for IP addresses, source location, and information on malicious IPs.
trafficSources.viaTorNodes boolean	Challenge traffic from The Onion Ring exit nodes to block bots and known bad devices. While TOR is used sometimes purely for Web anonymity, it is commonly used by hackers, scrapers, and spammers to crawl or hack Web applications.
trafficSources.viaProxyNetworks boolean	Challenge traffic from any known proxy network to block bots and known bad devices. While proxy services are used sometimes purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications.
trafficSources.viaHostingServices boolean	Challenge traffic from IP addresses known to be of hosting service companies. This rule is unlikely to see legitimate human traffic on these IP spaces since they are typically used for server hosting. In most cases, traffic from these IP spaces originate from infected servers that are controlled by hackers.
trafficSources.viaVpn boolean	Challenge traffic from any known VPN to block bots and known bad devices. While VPNs are sometimes used purely for Web anonymity, they are also commonly used by hackers, scrapers, and spammers to crawl or hack Web applications.
trafficSources.convictedBotTraffic boolean	Challenge traffic from IP addresses that have been convicted of automated activities (bots) on this site or on others. These IP addresses are used by malicious automated agents while no legitimate traffic has been observed on them.
trafficSources.suspiciousTrafficByLocalIpFormat boolean	Challenge traffic from suspicious NAT ranges.
antiAutomationBotProtection object	Block automated traffic from scanning and browsing your online application.
antiAutomationBotProtection.forceBrowserValidationOnTrafficAnomalies boolean	Challenge and block requests if the user or device behind them does not keep session cookies and does not execute JavaScripts correctly. Most malicious automated activities (bots) do not meet these conditions and will, therefore, effectively be blocked by the JavaScript challenge triggered in any suspected situation. Clients can also be blocked depending on whether they act in an abnormal to the specific domain—by scraping content in a way that most sessions on this domain don't—or clients that try to, for example, avoid detection by switching IPs.
antiAutomationBotProtection.challengeAutomatedClients boolean	Captcha-challenge and block sessions conducted by standard Web browsers if there is evidence that these sessions are being automated and not driven by a human user. Such automation is used primarily for screen scraping and other very targeted, site-specific malicious automation.
antiAutomationBotProtection.challengeHeadlessBrowsers boolean	Challenge requests if the user or device behind them uses an automation tool that initiates browsers but is actually an automation tool without real display—such as phantomJS, Selenium, or other. While such tools are favored by programmers, they are also extremely popular with scrapers, hackers and even in sophisticated DDoS attacks to circumvent standard anti-bot measures.
antiAutomationBotProtection.antiScraping boolean	A more hardened anti-automation policy that is meant to stop scrapers by using faster and harsher convictions.
spamAndAbuseForm boolean	Challenge and prevent automated tools from making HTTP/S Post requests without validating their session first.
cmsProtection object	Whitelist admin users.
cmsProtection.whiteListWordpress boolean	Enable whitelist WordPress admin logged-in users.
cmsProtection.whiteListModx boolean	Enable whitelist MODX admin logged-in users.
cmsProtection.whiteListDrupal boolean	Enable whitelist Drupal admin logged-in users.
cmsProtection.whiteListJoomla boolean	Enable whitelist Joomla admin logged-in users.
cmsProtection.whiteMagento boolean	Enable whitelist Magento admin logged-in users.
cmsProtection.whiteListOriginIp boolean	Enable this policy to whitelist requests coming from the origin for plugin updates and general CMS updates,
cmsProtection.whiteListUmbraco boolean	Enable whitelist Umbraco admin logged-in users.
behavioralWaf object	StackPath's sophisticated user behaviour and reputation analysis rules.
behavioralWaf.spamProtection boolean	Challenge and block user sessions and activities that seem to be aggressively using forms on your website to post spam content, generate new accounts, and more. Also, require a handshake (if not already provided) to clients making POST requests.
behavioralWaf.blockProbingAndForcedBrowsing boolean	Challenge or block sessions and users that seem to make brute-forced requests on random URLs seeking to discover a Web application's structure and hidden directories.
behavioralWaf.obfuscatedAttacksAndZeroDayMitigation boolean	Block clients performing multiple injection attacks.
behavioralWaf.repeatedViolations boolean	Challenge or block clients that failed to answer previous challenges.
behavioralWaf.bruteForceProtection boolean	Challenge and block attempts seeking to guess user names and passwords on Web login forms.
allowKnownBots object	An object containing known bots.

Firewall Rules

Deploy and manage Firewall Rules used to control and limit access to your sites.

List firewall rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/firewallrules?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "data": [
    {
        "action": "ALLOW",
        "enabled": "true",
        "id": "1533148",
        "ipEnd": "20.20.20.20",
        "ipStart": "10.10.10.10",
        "name": "Rule 1 ",
        "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb"
    },
    {
        "action": "BLOCK",
        "enabled": "true",
        "id": "1533345",
        "ipEnd": "192.1.1.2",
        "ipStart": "192.0.0.1",
        "name": "Rule 2 ",
        "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/firewallrules?siteId=:siteId

Query Params
action string	Filter IP addresses, which are either ALLOW or BLOCK. This parameter is optional. If not provided, it will return both the type of IP addresses.
siteId UUID	The ID of the site for which the firewall rule is applied to. This parameter is required.

Attributes
action string	Either ALLOW or BLOCK.
enabled boolean	Whether or not the rule is enabled.
id string	The unique identifier for the rule.
ipEnd string	The end ip adress for the rule.
ipStart string	The start ip adress for the rule.
name string	The name of the rule.
siteId UUID	The ID of the site for which the firewall rule is applied to.

Retrieve a firewall rule

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/firewallrules/1533148?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "data":{
    "action": "ALLOW",
    "enabled": "true",
    "id": "1533148",
    "ipEnd": "20.20.20.20",
    "ipStart": "10.10.10.10",
    "name": "Rule 1 ",
    "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb"
    },
}

GET /services/:service_code/:environment_name/firewallrules/:id?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which the firewall rule is applied to. This parameter is required.

Attributes
action string	Either ALLOW or BLOCK.
enabled boolean	Whether or not the rule is enabled.
id string	The unique identifier for the rule.
ipEnd string	The end ip adress for the rule.
ipStart string	The start ip adress for the rule.
name string	The name of the rule.
siteId UUID	The ID of the site for which the firewall rule is applied to.

Create a firewall rule

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/firewallrules?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"

Request body example for creating a firewall rule:

{
  "action": "ALLOW",
  "enabled": true,
  "ipEnd": "192.168.0.7",
  "ipStart": "192.168.0.6",
  "name": "firewall rule",
  "siteId": "1c6c127a-bfa4-4c85-a329-13c0581b41eb"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/firewallrules?siteId=:siteId

Restrict access to a site using allow and block rules.

Query Params
siteId UUID	The ID of the site for which to create the firewall rule. This parameter is required.

Required
action string	Either ALLOW or BLOCK.
ipStart string	The start ip adress for the rule. When no ipEnd attribute is provided, the rule only applies for the ip provided in ipStart.
name string	The name of the rule.

Optional
enabled boolean	Whether or not the rule is enabled. The default value is false.
ipEnd string	The end ip adress for the rule.
siteId UUID	The ID of the site for which the firewall rule is applied to.

Edit a firewall rule

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/firewallrules/1576836?siteId=1c6c127a-bfa4-4c85-a329-13c0581b41eb"

Request body example:

{
  "action": "ALLOW",
  "enabled": true,
  "id": "1576836",
  "ipEnd": "192.1.1.2",
  "ipStart": "192.0.0.1",
  "name": "allow.rule.cloudmc.xzp12",
  "siteId": "1c6c127a-bfa4-4c85-a329-13c0581b41eb"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/firewallrules/:id?siteId=:siteId

Edit a firewall rule.

Query Params
siteId UUID	The ID of the site for which the firewall rule is applied to. This parameter is required.

Required
action string	Either ALLOW or BLOCK.
ipStart string	The start ip adress for the rule.
name string	The name of the rule.

Optional
enabled boolean	Whether or not the rule is enabled. The default value is false.
id string	The unique identifier for the rule.
ipEnd string	The end ip adress for the rule.
siteId UUID	The ID of the site for which the firewall rule is applied to.

Delete a firewall rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/firewallrules/2318483?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/firewallrules/:id?siteId=:siteId

Delete a firewall rule

Query Params
siteId UUID	The ID of the site for which to delete the firewall rule. This parameter is required.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the firewall rule deletion.
taskStatus string	The status of the operation.

Scripts

Deploy and manage Serverless Scripts used to interact with requests made to the site.

List scripts

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/scripts?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "4d13a920-79b7-4129-957b-bd4f006b1ac8",
      "stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
      "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
      "name": "scriptName",
      "createdAt": "2021-03-15T19:05:45.157987Z",
      "updatedAt": "2021-03-15T19:05:45.157987Z",
      "version": "1",
      "routes": [
        "v1/api"
      ]
    },
    {
      "id": "28e6b0c7-ee5d-4bd3-abfb-13dfc6e15c0d",
      "stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
      "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
      "name": "scriptName2",
      "createdAt": "2021-03-15T18:53:18.587749Z",
      "updatedAt": "2021-03-15T18:53:18.587749Z",
      "version": "1",
      "routes": [
        "v1/api",
        "v2/api"
      ]
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/scripts?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which to list the scripts. This parameter is required.

Attributes
id UUID	The unique identifier for the script.
stackId UUID	The ID of the stack that the script belongs to.
siteId UUID	The ID of the site that the script belongs to.
name string	The display name of the script.
createdAt string	Creation timestamp of the script.
updatedAt string	The date on which the script was last updated.
version string	The version number of the script.
routes Array[string]	The routes that incoming requests should respond with a script.

Retrieve a script

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/scripts/439b145a-7c55-4a73-8cf2-d8faabfe6d22?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "4d13a920-79b7-4129-957b-bd4f006b1ac8",
    "stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
    "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
    "name": "scriptName1",
    "createdAt": "2021-03-15T19:05:45.157987Z",
    "updatedAt": "2021-03-15T19:05:45.157987Z",
    "code": "// sample script
    addEventListener('fetch', event => {
      event.respondWith(handleRequest(event.request));
    });

    /**
    * Fetch and return the request body
    * @param {Request} request
    */
    async function handleRequest(request) {
      // Wrap your script in a try/catch and return the error stack to view error information
      try {
        /* The request can be modified here before sending it with fetch */

        const response = await fetch(request);

        /* The response can be modified here before returning it */

        return response;
      } catch (e) {
        return new Response(e.stack || e, { status: 500 });
      }
    }",
    "version": "1",
    "routes": [
      "v1/api"
    ]
  }
}

GET /services/:service_code/:environment_name/scripts/:id?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which to list the scripts. This parameter is required.

Retrieve a script of a site in a given environment.

Attributes
id UUID	The unique identifier for the script.
stackId UUID	The ID of the stack that the script belongs to.
siteId UUID	The ID of the site that the script belongs to.
name string	The display name of the script.
createdAt string	Creation timestamp of the script.
updatedAt string	The date on which the script was last updated.
code string	The contents of the script.
version string	The version number of the script.
routes Array[string]	The routes that incoming requests should respond with a script.

Create a script

Create a new serverless script that allows you to run JavaScript code at the Edge, on all of PoPs with real-time access to each of the requests that come in for your site.

POST /services/:service_code/:environment_name/scripts?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which to create the script. This parameter is required.

Required
name string	The name of the script.
routes Array[string]	At least one route in the form of a URI.
code string	The JavaScript code used for the script.

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/scripts?siteId=:siteId"

Request body example for creating a script:

{
  "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
  "name": "script-name",
  "routes": ["route"],
  "code": "// sample script
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
});

/**
 * Fetch and return the request body
 * @param {Request} request
 */
async function handleRequest(request) {
  // Wrap your script in a try/catch and return the error stack to view error information
  try {
    /* The request can be modified here before sending it with fetch */

    const response = await fetch(request);

    /* The response can be modified here before returning it */

    return response;
  } catch (e) {
    return new Response(e.stack || e, { status: 500 });
  }
}"
}

The above command returns a JSON structured like this:

{
  "taskId": "dfc0b899-ac0f-447b-8f50-74bf78d1c034",
  "taskStatus": "PENDING"
}

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to creation of the script.
taskStatus string	The status of the operation.

Edit a script

Edit a script in a given environment for a given site ID.

curl -X PUT \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/scripts/dd207010-4570-43ee-9ff2-5421d2306b41?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

Request body example for editing a script:

{
  "routes": ["route"],
  "code": "console.log('hello')"
}

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/scripts/:id?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which to edit the script. This parameter is required.

Optional
routes Array[string]	At least one route in the form of a URI.
code string	The JavaScript code used for the script or the Base64 encoded contents of the script

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to creation of the script.
taskStatus string	The status of the operation.

Delete a script

Delete a script in a given environment for a given site ID.

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/scripts/dd207010-4570-43ee-9ff2-5421d2306b41?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/scripts/:id?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which to delete the script. This parameter is required.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the script deletion.
taskStatus string	The status of the operation.

EdgeSSL

EdgeSSL Settings

View and manage SSL settings.

Retrieve EdgeSSL settings

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/edgesslsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
    "forceHttps": true,
    "minTlsVersion": "V1_2"
  }
}

GET /services/:service_code/:environment_name/edgesslsettings/:id

Retrieve the EdgeSSL settings for a site in a given environment.

Attributes
id UUID	A site's unique identifier.
forceHttps boolean	Whether the site redirects all visitors to use HTTPS instead of HTTP.
minTlsVersion string	The minimum TLS version clients must have to access the application.

Edit EdgeSSL settings

curl -X PATCH \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/edgesslsettings/eb3ecdbe-d73b-40e6-a263-166accba75ed"

The above command returns a JSON structured like this:

{
    "forceHttps": "true",
    "minTlsVersion": "V1_2"
}

PATCH /services/:service_code/:environment_name/edgesslsettings/:id

Edit the EdgeSSL settings for a site in a given environment.

Attributes
forceHttps boolean	Whether the site redirects all visitors to use HTTPS instead of HTTP.
minTlsVersion string	The minimum TLS version clients must have to access the application.

One or both of these attributes can be updated at the same time.

Certificates

Add Secure Socket Layer (SSL) features to a site.

List certificates

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/certificates?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this: json { "data": [ { "id": "2a12237d-c388-4c19-bff1-b019b837e8f1", "issuer": "Let's Encrypt", "caBundle": "-----BEGIN CERTIFICATE----- MIIEZTCCA02gAwIBAgIQQAF1BIMUpMghjISpDBbN3zANBgkqhkiG9w0BAQsFADA/ MSQwIgY...", "status": "failed", "expiresAt": "2021-04-01T18:11:11.903458Z", "commonName": "helloworld.com", "createdAt": "2021-04-01T18:11:11.904285Z", "isManaged": true, "trusted": false, "updatedAt": "2021-04-04T18:30:32.021842Z" } ], "metadata": { "recordCount": 1 } }

GET /services/:service_code/:environment_name/certificates?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which the certificate is applied to. This parameter is required.

Attributes
id UUID	The unique identifier of the certificate.
siteId UUID	The unique identifier of the site for which the certificate is applied to.
issuer string	The authority who issued the certificate.
caBundle string	A PEM PKCS #7 formatted certificate authority bundle.
status string	A SSL certificate status.
expiresAt string	The date the certificate will expire and the status updated to EXPIRED.
commonName string	A certificate's common name, or the primary domain name the certificate is used for.
createdAt string	The date the certificate was created.
updatedAt string	The last time a certificate was updated by the provisioning process.
isManaged boolean	Whether a certificate is managed by StackPath or the end user.
trusted boolean	Whether or not the certificate's authority is trusted by a web browser.

List of possible values for the status attribute:

status
UNKNOWN	StackPath is unable to determine the certificate's status. This is the default status for end-user provided certificates.
PENDING	The certificate is provisioning.
EXPIRED	The certificate has expired.
FAILED	The certificate failed to provision.
PENDING_VERIFICATION	The certificate is pending domain verification by the end user.
ACTIVE	The certificate is valid and is in use by one or more hosts.
INACTIVE	The certificate is valid but is not in use by any hosts.

Retrieve a certificate

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/certificates/2a12237d-c388-4c19-bff1-b019b837e8f1?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this: json { "data": { "id": "2a12237d-c388-4c19-bff1-b019b837e8f1", "issuer": "Let's Encrypt", "caBundle": "-----BEGIN CERTIFICATE----- MIIEZTCCA02gAwIBAgIQQAF1BIMUpMghjISpDBbN3zANBgkqhkiG9w0BAQsFADA/ MSQwIgY...", "status": "failed", "expiresAt": "2021-04-01T18:11:11.903458Z", "commonName": "helloworld.com", "createdAt": "2021-04-01T18:11:11.904285Z", "isManaged": true, "trusted": false, "updatedAt": "2021-04-04T18:30:32.021842Z" } }

GET /services/:service_code/:environment_name/certificates/:id?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which the certificate is applied to. This parameter is required.

Attributes
id UUID	The unique identifier of the certificate.
siteId UUID	The unique identifier of the site for which the certificate is applied to.
issuer string	The authority who issued the certificate.
caBundle string	A PEM PKCS #7 formatted certificate authority bundle.
status string	A SSL certificate status.
expiresAt string	The date the certificate will expire and the status updated to EXPIRED.
commonName string	A certificate's common name, or the primary domain name the certificate is used for.
createdAt string	The date the certificate was created.
updatedAt string	The last time a certificate was updated by the provisioning process.
isManaged boolean	Whether a certificate is managed by StackPath or the end user.
trusted boolean	Whether or not the certificate's authority is trusted by a web browser.

List of possible values for the status attribute:

status
UNKNOWN	StackPath is unable to determine the certificate's status. This is the default status for end-user provided certificates.
PENDING	The certificate is provisioning.
EXPIRED	The certificate has expired.
FAILED	The certificate failed to provision.
PENDING_VERIFICATION	The certificate is pending domain verification by the end user.
ACTIVE	The certificate is valid and is in use by one or more hosts.
INACTIVE	The certificate is valid but is not in use by any hosts.

Create a certificate

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/certificates?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"

Request body example for creating a certificate:

{
  "certificate": "-----BEGIN CERTIFICATE----- X509 certificate content -----END CERTIFICATE-----",
  "key": "-----BEGIN PRIVATE KEY----- Private key of the certificate -----END PRIVATE KEY-----",
  "caBundle": "-----BEGIN CERTIFICATE----- Certificate authority bundle  -----END CERTIFICATE-----"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/certificates?siteId=:siteId

Create a certificate that will automatically be assigned to the site based on the hostnames of the certificate.

Query Params
siteId UUID	The ID of the site. This parameter is required.

Required
certificate string	The X509 certificate.
key string	The private key of the certificate.

Optional
caBundle string	The certificate authority bundle.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to creation of the certificate.
taskStatus string	The status of the operation.

Request a certificate

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/certificates?operation=request&siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"

Request body example for requesting a certificate:

{
  "hosts": [
        {"domain": "helloworld.com"},
        {"domain": "www.helloworld.com"}
    ],
    "verificationMethod": "DNS"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/certificates?operation=request&siteId=:siteId

Request a certificate that will automatically be assigned to the site.

Query Params
siteId UUID	The ID of the site. This parameter is required.

Required
verificationMethod Enum	The verification method used to validate a requested certificate on a site. Possible values are: DNS and HTTP.

Optional

hosts Array[string]

A list of delivery domains that will be included as subject alternative names on the certificate. If no hosts are provided, all delivery domains on the site will be included with the first one in the list being used as the common name. If hosts are provided, the first entry will be used as the common name. If the first host in the list is over 63 characters the shortest host provided will be used as the common name.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to creation of the certificate.
taskStatus string	The status of the operation.

Delete a certificate

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/certificates/2318483?siteId=6f6c1724-c306-433c-9e09-95227edc7c6c"

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/certificates/:id?siteId=:siteId

Delete a certificate.

Query Params
siteId UUID	The ID of the site for which to delete the certificate. This parameter is required.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the certificate deletion.
taskStatus string	The status of the operation.

EdgeRules

Predefined EdgeRules

The predefined EdgeRules let you configure how StackPath responds to requests to your website. These predefined EdgeRules only work with domains that resolve to StackPath.

List predefined EdgeRules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/predefinededgerules/dcc2771d-a524-4f8c-a666-f699985d6961"

The above command returns a JSON structured like this:

{
  "data": {
    "allowEmptyReferrer": false,
    "forceWwwEnabled": true,
    "id": "c988cc62-24e7-4850-9a81-95f51af0a68e",
    "pseudoStreamingEnabled": true,
    "referrerList": [
      "cloudmc.io",
      "saas.cloudmc.io"
    ],
    "referrerProtectionEnabled": true,
    "robotsTxtEnabled": true,
    "robotsTxtFile": "User-agent: *\nDisallow:",
    "scopeId": "e9e48610-3ba6-471a-96f4-7cf18cb73455",
    "stackId": "1f259d02-db66-4a93-8402-a0725a00a02a",

  }
}

GET /services/:service_code/:environment_name/predefinededgerules/:siteId

Retrieve the configuration of all predefined EdgeRules in a given environment within a site.

Attributes
allowEmptyReferrer boolean	Whether or not empty referrer is allowed.
forceWwwEnabled boolean	Whether or not redirecting every request to a www subdomain is enabled.
id UUID	This ID is same as the siteId to which the predefined EdgeRules belong.
pseudoStreamingEnabled boolean	Whether or not seeking random locations within MP4 or FLV files without downloading the entire video is enabled.
referrerList Array[string]	The list of domains authorized to access content from the site's root scope. Wildcards can be used to specify multiple websites hosted on the same domain.
referrerProtectionEnabled boolean	Whether or not referrer protection is enabled. This rule is used to allow only requests whose referrer header matches a URL that you specified.
robotsTxtEnabled boolean	Whether or not custom robot.txt support is enabled. This rule is used to configure which pages or files search engine crawlers can or cannot index from the site.
robotsTxtFile string	This field represents the robots.txt file contents. NOTE: When you first enable the robotsTxtEnabled rule, by default, the robots.txt will populate with a rule to disallow all indexing for CDN content. Any change made with this rule will override the contents of the robots.txt file on origin server.
scopeId UUID	The ID of the CDN site's root scope that the predefined rules belongs to.
stackId UUID	The ID of the stack that the predefined rules belong to.

Edit a predefined EdgeRules

curl -X PATCH \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/predefinededgerules/dcc2771d-a524-4f8c-a666-f699985d6961"

Request body example:

{
  "allowEmptyReferrer": true,
  "forceWwwEnabled": true,
  "pseudoStreamingEnabled": true,
  "referrerList": [
    "cloudmc.com",
    "saas.cloudmc.com"
  ],
  "referrerProtectionEnabled": true,
  "robotsTxtEnabled": true,
  "robotsTxtFile": "User-agent: *\nDisallow:",
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

PATCH /services/:service_code/:environment_name/predefinededgerules/:siteId

Optional
allowEmptyReferrer boolean	Whether or not empty referrer is allowed.
forceWwwEnabled boolean	Whether or not redirecting every request to a www subdomain is enabled.
pseudoStreamingEnabled boolean	Whether or not seeking random locations within MP4 or FLV files without downloading the entire video is enabled.
referrerList Array[string]	The list of domains authorized to access content from the site's root scope. Wildcards can be used to specify multiple websites hosted on the same domain.
referrerProtectionEnabled boolean	Whether or not referrer protection is enabled. This rule is used to allow only requests whose referrer header matches a URL that you specified.
robotsTxtEnabled boolean	Whether or not custom robot.txt support is enabled.
robotsTxtFile string	This field represents the robots.txt file contents. NOTE: To update the robotsTxtFile content, the robotsTxtEnabled flag should be included in the request payload.

Custom Rules

Manage custom rules used to control and limit access to your sites.

List custom rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/customrules?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "1580676",
      "stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95cXXX",
      "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
      "name": "testrequestrate",
      "notes": "test-note",
      "type": "WAF",
      "enabled": true,
      "action": "BLOCK",
      "actionDuration": "0s",
      "statusCode": "FORBIDDEN_403",
      "conditions": [
        {
          "type": "IP",
          "operation": "EQUAL",
          "value": "120.1.1.1"
        }
      ]
    },
    {
      "id": "1580692",
      "stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95cXXX",
      "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
      "name": "testipwafrule",
      "notes": "",
      "type": "REQUEST_RATE",
      "enabled": true,
      "action": "ALLOW",
      "actionDuration": "0s",
      "statusCode": "TOO_MANY_REQUESTS_429",
      "nbRequest": 20,
      "duration": 60,
      "pathRegExp": "/",
      "httpMethods": [],
      "ipAddresses": []
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/customrules?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which the custom rule is applied to. This parameter is required.

Attributes
id string	The unique identifier for the rule.
stackId UUID	The ID of the stack for which the custom rule is applied to.
siteId UUID	The ID of the site for which the custom rule is applied to.
name string	The name of the rule.
notes string	The description notes of the rule.
type string	Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions.
enabled boolean	Whether or not the rule is enabled.
action string	Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR.
actionDuration string	How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s
statusCode string	A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403.
nbRequest long	Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE.
duration long	Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE.
pathRegExp string	The regex expression present in the path for the rule to trigger. Only for rule of type REQUEST_RATE.
httpMethods Array[string]	List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE. Possible values are: GET, POST, PUT, DELETE, HEAD, PATCH, OPTION, CONNECT, TRACE.
ipAddresses Array[string]	List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE.
conditions Array[Object]	The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF.
conditions.type string	Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION.
conditions.operation string	Operation of the condition, one of: EQUAL, NOT_EQUAL for all condition type except IP_RANGE , CONTAINS, NOT_CONTAINS for condition type HEADER, URL and USER_AGENT BETWEEN or NOT_BETWEEN only for condition type IP_RANGE .
conditions.header string	Value of the header. Only for condition of type HEADER.
conditions.value string	Value for which the condition holds.
conditions.endValue string	Second value of the condition. Only for condition of type IP_RANGE.

Retrieve a custom rule

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/customrules/1580676?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

The above command returns a JSON structured like this:

{
  "data": {
      "id": "1580676",
      "stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95cXXX",
      "siteId": "0a57855b-26d8-4e8f-8b77-429997c7c5fb",
      "name": "testrequestrate",
      "notes": "test-note",
      "type": "WAF",
      "enabled": true,
      "action": "BLOCK",
      "actionDuration": "0s",
      "statusCode": "FORBIDDEN_403",
      "conditions": [
        {
          "type": "IP",
          "operation": "EQUAL",
          "value": "120.1.1.1"
        }
      ]
    }
}

GET /services/:service_code/:environment_name/customrules/:id?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which the custom rule is applied to. This parameter is required.

Attributes
id string	The unique identifier for the rule.
stackId UUID	The ID of the stack for which the custom rule is applied to.
siteId UUID	The ID of the site for which the custom rule is applied to.
name string	The name of the rule.
notes string	The description notes of the rule.
type string	Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions.
enabled boolean	Whether or not the rule is enabled.
action string	Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR.
actionDuration string	How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s
statusCode string	A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403.
nbRequest long	Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE.
duration long	Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE.
pathRegExp string	The regex expression present in the path for the rule to trigger. Only for rule of type REQUEST_RATE.
httpMethods Array[string]	List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE. Possible values are: GET, POST, PUT, DELETE, HEAD, PATCH, OPTION, CONNECT, TRACE.
ipAddresses Array[string]	List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE.
conditions Array[Object]	The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF.
conditions.type string	Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION.
conditions.operation string	Operation of the condition, one of: EQUAL, NOT_EQUAL for all condition type except IP_RANGE , CONTAINS, NOT_CONTAINS for condition type HEADER, URL and USER_AGENT BETWEEN or NOT_BETWEEN only for condition type IP_RANGE .
conditions.header string	Value of the header. Only for condition of type HEADER.
conditions.value string	Value for which the condition holds.
conditions.endValue string	Second value of the condition. Only for condition of type IP_RANGE.

Create a custom rule

curl -X POST \
    -H "MC-Api-Key: your_api_key" \
    -d "request_body" \
    "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/customrules?siteId=0a57855b-26d8-4e8f-8b77-429997c7c5fb"

Request body example for a custom rule with conditions:

{
  "name": "firewall.allow",
  "notes": "some firewall note",
  "type": "WAF",
  "action": "BLOCK",
  "actionDuration": "0s",
  "statusCode": "FORBIDDEN_403",
  "conditions": [
    {
      "type": "IP",
      "operation": "EQUAL",
      "value": "120.1.1.1"
    }
  ]
}

Request body example for a custom role with request rate:

{
  "name": "firewall.deny",
  "notes": "Deny rule",
  "type": "REQUEST_RATE",
  "action": "BLOCK",
  "actionDuration": "0s",
  "statusCode": "TOO_MANY_REQUESTS_429",
  "nbRequest": 20,
  "duration": 60,
  "pathRegExp": "/",
  "httpMethods": ["GET"],
  "ipAddresses": ["192.168.2.1"]
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/customrules?siteId=:siteId

Create a custom rule for a site in a given environment.

Query Params
siteId UUID	The ID of the site for which the custom rule is applied to. This parameter is required.

Required
name string	The name of the rule.
type string	Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions.
action string	Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR.
nbRequest long	Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE.
duration long	Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE.
conditions Array[Object]	The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF.
conditions.type string	Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION.
conditions.operation string	Operation of the condition, one of: EQUAL, NOT_EQUAL for all condition type except IP_RANGE , CONTAINS, NOT_CONTAINS for condition type HEADER, URL and USER_AGENT BETWEEN or NOT_BETWEEN only for condition type IP_RANGE .
conditions.header string	Value of the header. Only for condition of type HEADER.
conditions.value string	Value for which the condition holds.
conditions.endValue string	Second value of the condition. Only for condition of type IP_RANGE.

Optional
notes string	The description notes of the rule.
actionDuration string	How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s
statusCode string	A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403.
pathRegExp string	The regex expression that the path must match for the rule to trigger. Default is '/'. Only for rule of type REQUEST_RATE.
httpMethods Array[string]	List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE.
ipAddresses Array[string]	List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE.

Create a WAF rule based on a request made to an existing site

POST "https://cloudmc_endpoint/api/v1/services/{serviceCode}/{environment}/wafrequests/{wafrequestId}?operation=create_rule&siteId={siteId}"

curl -X POST \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/stackpath-aaaa/env-1/wafrequests/197d190d415bea5ea1385a0de6f3bceb-452444?operation=create_rule&siteId=5ea00192-30f0-4da0-b9d9-461baa3dde89"

Request body example for the custom rule:

{
    "action": "MONITOR",
    "clientIp": "66.249.82.90"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

Path Params
serviceCode string	The globally unique serviceCode that identifies the service connection.
wafrequestId UUID	The ID of the WAF request made to the site. The WAF rule created must map to an existing request made to the site.
environment UUID	The name of the environment containing the site.

Query Params
operation string	The operation executed. This must be create_rule.
siteId UUID	The ID of the site for which the custom rule is applied to. This parameter is required.

Required
action string	The action to be taken on the provided IP address. The action must be one of ALLOW, BLOCK, MONITOR, CAPTCHA, or HANDSHAKE.
clientIp string	The IP address the WAF request specified was made from.

Edit a custom rule

curl -X PUT \
  -H "MC-Api-Key: your_api_key" \
  -d "request_body" \
  "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/customrules/1576836?siteId=1c6c127a-bfa4-4c85-a329-13c0581b41eb"

Request body example for a custom rule with conditions:

{
  "name": "firewalldeny",
  "notes": "Deny rule",
  "type": "WAF",
  "enabled": false,
  "action": "BLOCK",
  "actionDuration": "10s",
  "statusCode": "FORBIDDEN_403",
  "conditions": [
    {
      "type": "IP",
      "operation": "EQUAL",
      "value": "172.16.254.14"
    }
  ]
}

Request body example for a custom role with request rate:

{
  "name": "firewalldeny",
  "notes": "Deny rule",
  "type": "REQUEST_RATE",
  "action": "BLOCK",
  "actionDuration": "0s",
  "statusCode": "TOO_MANY_REQUESTS_429",
  "nbRequest": 20,
  "duration": 60,
  "pathRegExp": "/",
  "httpMethods": ["GET"],
  "ipAddresses": ["192.168.2.1"]
}

The above commands returns a JSON structured like this:

{
  "taskId": "8fcf30b0-1644-474d-b150-ac0c6f51bf98",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/customrules/:id?siteId=:siteId

Edit a custom rule.

Query Params
siteId UUID	The ID of the site for which the custom rule is applied to. This parameter is required.

Required
name string	The name of the rule.
type string	Type of custom rule. One of REQUEST_RATE or WAF. The fields returned are different based on the type, REQUEST_RATE will not return a list of conditions.
action string	Action to be taken when the rule is met. Possible values are ALLOW, BLOCK, CAPTCHA,HANDSHAKE or MONITOR.
nbRequest long	Number of dynamic page requests made for the rule to trigger. Only for rule of type REQUEST_RATE.
duration long	Number of seconds that the WAF measures incoming requests over for the rule to trigger. Only for rule of type REQUEST_RATE.
conditions Array[Object]	The conditions required for the WAF engine to trigger the rule. All conditions must pass for the rule to trigger. Only for rule of type WAF.
conditions.type string	Type of condition, one of: IP, IP_RANGE, URL, USER_AGENT, HEADER, HTTP_METHOD, FILE_EXTENSION, CONTENT_TYPE, COUNTRY or ORGANIZATION.
conditions.operation string	Operation of the condition, one of: EQUAL, NOT_EQUAL for all condition type except IP_RANGE , CONTAINS, NOT_CONTAINS for condition type HEADER, URL and USER_AGENT BETWEEN or NOT_BETWEEN only for condition type IP_RANGE .
conditions.header string	Value of the header. Only for condition of type HEADER.
conditions.value string	Value for which the condition holds.
conditions.endValue string	Second value of the condition. Only for condition of type IP_RANGE.

Optional
notes string	The description notes of the rule.
actionDuration string	How long a rule's block action will apply to subsequent requests in case of the action BLOCK. Format is a string with a integer followed by the unit (s for seconds, m for minutes and h for hours e.g. 30s). Default is 0s
statusCode string	A custom HTTP status code that the WAF returns if a rule blocks a request. Possible values are FORBIDDEN_403 and TOO_MANY_REQUESTS_429. Default is FORBIDDEN_403.
pathRegExp string	The regex expression that the path must match for the rule to trigger. Default is '/'. Only for rule of type REQUEST_RATE.
httpMethods Array[string]	List of HTTP methods that the rule will apply to. Only for rule of type REQUEST_RATE.
ipAddresses Array[string]	List of IP addresses that the rule will apply to. Only for rule of type REQUEST_RATE.

Delete a custom rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/customrules/1585477?siteId=1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36"

The above command returns a JSON structured like this:

{
  "taskId": "c39f0c66-04a0-40cf-aa2e-485f50a27561",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/customrules/:id?siteId=:siteId

Delete a custom rule

Query Params
siteId UUID	The ID of the site for which to delete the custom rule. This parameter is required.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the custom rule deletion.
taskStatus string	The status of the operation.

Enable a custom rule

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/customrules/1585477?siteId=1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36&operation=enable"

The above command returns a JSON structured like this:

{
  "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd",
  "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/customrules/:id?siteId=:siteId&operation=enable

Query Params
siteId UUID	The ID of the site for which the rule belongs to. This parameter is required.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the operation.
taskStatus string	The status of the operation.

Disable a custom rule

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/customrules/1585477?siteId=1b1cd7e6-41ab-4e0f-a59a-5c4b89da1b36&operation=disable"

The above command returns a JSON structured like this: json { "taskId": "57fc8d89-6f13-451b-8b66-fcd96e1fedbd", "taskStatus": "SUCCESS" }

POST /services/:service_code/:environment_name/customrules/:id?siteId=:siteId&operation=disable

Query Params
siteId UUID	The ID of the site for which the rule belongs to. This parameter is required.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the operation.
taskStatus string	The status of the operation.

Delivery Rules

Set up delivery rules to improve access, security and set custom rules.

List delivery rules

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliveryrules?siteId=dcc2771d-a524-4f8c-a666-f699985d6961"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "fc72c60a-d411-4b35-9deb-9dbc889faf7e",
      "name": "addHeader",
      "slug": "portal-ui-custom-1617310238955",
      "stackId": "fd157f7c-e5cd-439b-b6c5-5864583a8ce8",
      "siteId": "dcc2771d-a524-4f8c-a666-f699985d6961"
    },
    {
      "id": "d411c60a-d411-4b35-9deb-f699985d6961",
      "name": "removeHeader",
      "slug": "portal-ui-custom-1617310238955",
      "stackId": "fd157f7c-e5cd-439b-b6c5-5864583a8ce8",
      "siteId": "dcc2771d-a524-4f8c-a666-f699985d6961"  
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/deliveryrules?siteId=:siteId

Retrieve a list of all delivery rules in a given environment within a site.

Attributes
id UUID	A delivery rule's unique identifier.
name string	The name of the delivery rule.
slug string	A delivery rule's programmatic name.
stackId string	The ID of the stack that the delivery rule belongs to.
siteId string	The ID of the site that the delivery rule is applied to.

Create a delivery rule

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliveryrules?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"

Request body example for creating a delivery rule:

{
 "name": "rule",
  "conditions": [
  {
    "trigger": "HEADER",
    "operator": "MATCHES",
    "target": "my-header"
  }],
  "actions": [
    {
      "actionType": "REDIRECT",
      "redirectUrl": "https://my-url.com"
    }]
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/deliveryrules?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which to create the delivery rule. This parameter is required.

Required
name string	The name of the delivery rule.
conditions Array[Condition]	At least one condition.
actions Array[Action]	At least one action.

Update a delivery rule

curl -X PUT \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliveryrules/d065db45-1eba-4c62-a017-d51f2d473d4a?siteId=f9dea588-d7ab-4f42-b6e6-4b85f273f3db"

Request body example for updating a delivery rule:

{
  "conditions": [
  {
    "trigger": "HEADER",
    "operator": "MATCHES",
    "target": "my-header"
  }],
  "actions": [
    {
      "actionType": "REDIRECT",
      "redirectUrl": "https://my-url.com"
    }]
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/deliveryrules/:ruleId?siteId=:siteId

Query Params
siteId UUID	The ID of the site for which to update the delivery rule. This parameter is required.

Required
conditions Array[Condition]	At least one condition.
actions Array[Action]	At least one action.

Delete a delivery rule

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/deliveryrules/90d6a6ed-05a5-4b45-8d5a-e8229f535149?siteId=1c6c127a-bfa4-4c85-a329-13c0581b41eb"

The above command returns a JSON structured like this:

{
  "taskId": "2c7429dc-64c2-492d-a767-f18c990af164",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/deliveryrules/:id?siteId=:siteId

Delete a delivery rule.

Query Params
siteId UUID	The ID of the site for which to delete the delivery rule. This parameter is required.

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the delivery rule deletion.
taskStatus string	The status of the operation.

Condition

Required
trigger Enum	Trigger for the condition. Possible values: COOKIE, HEADER, HTTP_METHOD, STATUS_CODE, and URL.
operator Enum	Operator for the condition. Possible values: EQUALS, MATCHES, and MATCHES_REGULAR_EXPRESSION.
target String	The target of the condition.
httpMethods Array[Enum]	HTTP methods for the condition. Possible values are: GET, POST, PUT, DELETE, HEAD, PATCH, and OPTIONS. This fields is only used when trigger is set to HTTP_METHOD.

Action

The action attributes needed to be passed will vary depending on the condition being specified.

Possible Attributes
actionType Enum	The type of action. Possible values: ADD_RESPONSE_HEADER, ADD_HEADER_TO_ORIGIN,ADD_HEADER_TO_CDN, NEVER_EXPIRE, DO_NOT_CACHE, CACHE, REDIRECT, HIDE_HEADER, MODIFY_HEADER, SIGN_URL, and BYPASS_CACHE.
responseHeaders Array	Headers for the actions expressed as a key-value pair.
originHeaders Array	Headers for the actions expressed as a key-value pair.
cdnHeaders Array	Headers for the actions expressed as a key-value pair.
cacheTtl Number	Time to live of the cache.
redirectUrl String	The url to redirect to.
headerPattern String	The header to set the modifier in the response.
passphrase String	The passphrase for signing the url.
passphraseField String	The passphrase field for signing the url.
md5TokenField String	The MD5 token field for signing the url.
ipAddressFilter String	The ip address filter for signing the url.
urlSignaturePathLength String	The url signature path length for signing the url.

Images

StackPath Edge Computing makes use of images to deploy virtual machines within a workload. The image can be from StackPath default images or a custom one. Only non-deprecated images are returned by default.

Deploy and manage your images.

List images

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/images"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "stackId": "a8050b2b-39eb-4929-bce5-1af42055903e",
      "id": "a8050b2b-39eb-4929-bce5-1af42055903e/centos7/v20201110",
      "slug": "stackpath-edge",
      "family": "centos7",
      "tag": "v20201110",
      "createdAt": "2020-11-10T20:33:32.609434Z",
      "description": "Image using centos7",
      "reference": "stackpath-edge/centos7:v20201110",
      "status": "READY"
    },
    {
      "stackId": "a8050b2b-39eb-4929-bce5-1af42055903e",
      "id": "a8050b2b-39eb-4929-bce5-1af42055903e/ubuntu/v20201110",
      "slug": "stackpath-edge",
      "family": "ubuntu",
      "tag": "v20201110",
      "createdAt": "2020-11-10T20:34:11.328575Z",
      "description": "Image using ubuntu",
      "reference": "stackpath-edge/ubuntu:v20201110",
      "status": "READY"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/images

Retrieve a list of all images in a given environment.

Optional
imageType string	This query parameter can either be set to default to return the default StackPath images or custom to return the created custom images. Anything else will return all images.

Attributes
id string	An image's unique identifier. It is the combination of stackId/family/tag.
stackId string	The ID of the stack that an image belongs to.
family string	The family of the image.
tag string	The tag of the image.
slug string	A workload's programmatic name. Workload slugs are used to build its instances names.
status string	The status of the workload. It can be either READY, PENDING, PROCESSING, FAILED or IMAGE_STATUS_UNKNOWN.
createdAt string	Creation timestamp of the image.
description string	The description of the image.
reference string	The reference of the image.

Retrieve an image

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/images/a8050b2b-39eb-4929-bce5-1af42055903e/ubuntu/v20201110"

The above command returns a JSON structured like this:

{
  "data": {
    "stackId": "a8050b2b-39eb-4929-bce5-1af42055903e",
    "id": "a8050b2b-39eb-4929-bce5-1af42055903e/ubuntu/v20201110",
    "slug": "stackpath-edge",
    "family": "ubuntu",
    "tag": "v20201110",
    "createdAt": "2020-11-10T20:34:11.328575Z",
    "description": "test 2",
    "reference": "stackpath-edge/ubuntu:v20201110",
    "status": "READY"
  }
}

GET /services/:service_code/:environment_name/images/:id

Retrieve an image in a given environment.

Attributes
id string	An image's unique identifier. It is the combination of stackId/family/tag.
stackId string	The ID of the stack that an image belongs to.
family string	The family of the image.
tag string	The tag of the image.
slug string	A workload's programmatic name. Workload slugs are used to build its instances names.
status string	The status of the workload. It can be either READY, PENDING, PROCESSING, FAILED or IMAGE_STATUS_UNKNOWN.
createdAt string	Creation timestamp of the image.
description string	The description of the image.
reference string	The reference of the image.

Create a custom image

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/images"

Request body example for creating a custom image:

{
  "family": "Ubuntu",
  "tag": "v2021-01-01",
  "workloadId": "c23652ed-0f15-47cf-a9b8-63e1e3aacb3c",
  "instanceName": "w-john-ahd-wi-john-jsr-phx-0",
  "description": "Ubuntu OS v4"
}

The above commands return a JSON structured like this:

{
  "taskId": "1f64aefb-f980-400b-bc2d-5300376fa55e",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/images

Required
family string	The family name of the custom image.Family must consist of lower case alphanumeric characters or '-' and must begin and end with an alphanumeric character.
tag string	The tag of the image. A tag must be valid ASCII and may contain lowercase and uppercase letters, digits, underscores, periods and dashes. A tag must not start with a period or a dash and must contain a maximum of 128 characters.
workloadId string	The workloadId of the source workload the image will be created from. Only workloads of type VM are allowed
instanceName string	The name of one of the instance the create the image from. The name of the instance needs to be a valid instance of the workloadId provided.

Optional
description string	The description of the custom image.

Delete a custom image

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/images/1b932678-1038-4ab4-9fa4-c4c06e696e20"

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/images/:id

Delete an image in a given environment.

Attributes
taskId string	The task id related to the image deletion.
taskStatus string	The status of the operation.

DNS Zones

Create and manage your DNS zones.

List DNS Zones

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnszones"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
      "accountId": "69b60c67-6175-4515-bb66-033108306X66",
      "domain": "mydomain.com",
      "version": "3",
      "created": "2021-07-28T17:13:42.863239Z",
      "updated": "2021-07-28T17:14:25.246331Z",
      "nameservers": [
        "xx2xx0.stackpathdns.net",
        "ss3xx3.stackpathdns.net"
      ],
      "disabled": false,
      "id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
      "verified": "2021-07-28T17:14:25.246331Z",
      "status": "ACTIVE"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/dnszones

Retrieve a list of all DNS zones in a given environment.

Attributes
id string	A zone's unique identifier.
stackId string	The ID of the stack that a site belongs to.
accountId string	The ID of the StackPath account that owns a zone.
domain string	The name of the zone.
version string	The version of the zone. Version numbers are incremented automatically when a zone is updated.
created string	The date on which the DNS zone was created.
updated string	The date on which the DNS zone was last updated.
nameservers Array[string]	The hostnames of the StackPath resolvers that host a zone. Every zone has multiple name servers assigned by StackPath upon creation for redundancy purposes.
disabled boolean	Whether or not a zone has been disabled by the user.
verified string	The date a zone's nameservers were last audited by StackPath.
status string	The status of the zone. It can either be ACTIVE, INACTIVE.

Retrieve a DNS zone

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnszones/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5"

The above command returns a JSON structured like this:

{
  "data": {
    "stackId": "87e22df5-cac9-4e42-9b75-02996af95566",
    "accountId": "69b60c67-6175-4515-bb66-033108306X66",
    "domain": "mydomain.com",
    "version": "3",
    "created": "2021-07-28T17:13:42.863239Z",
    "updated": "2021-07-28T17:14:25.246331Z",
    "nameservers": [
      "xx2xx0.stackpathdns.net",
      "ss3xx3.stackpathdns.net"
    ],
    "disabled": false,
    "id": "eb3ecdbe-d73b-40e6-a263-166accba75ed",
    "verified": "2021-07-28T17:14:25.246331Z",
    "status": "ACTIVE"
  }
}

GET /services/:service_code/:environment_name/dnszones/:id

Retrieve a DNS zone in a given environment.

Attributes
id string	A zone's unique identifier.
stackId string	The ID of the stack that a site belongs to.
accountId string	The ID of the StackPath account that owns a zone.
domain string	The name of the zone.
version string	The version of the zone. Version numbers are incremented automatically when a zone is updated.
created string	The date on which the DNS zone was created.
updated string	The date on which the DNS zone was last updated.
nameservers Array[string]	The hostnames of the StackPath resolvers that host a zone. Every zone has multiple name servers assigned by StackPath upon creation for redundancy purposes.
disabled boolean	Whether or not a zone has been disabled by the user.
verified string	The date a zone's nameservers were last audited by StackPath.
status string	The status of the zone. It can either be ACTIVE, INACTIVE.

Create a DNS zone

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnszones"

Request body example for without DNS records to import:

{
  "domain":"my-domain.com"
}

Request body example for with DNS records to import:

{
  "domain": "my-domain.com",
  "records": [
    {
      "name": "*",
      "type": "NS",
      "ttl": 3600,
      "data": "ns1.above.com.",
      "weight": 1
    }
  ]
}

The above command returns a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/dnszones

Create a DNS zone in a given environment.

Required
domain String	The name of the zone.

Optional
records Array[Object]	The list of DNS records to create.
records.type String	A zone record's type. Zone record types describe the zone record's behavior. Supported values are A, AAAA, CAA, CNAME, MX, SRV, TXT or NS. Required for each record.
records.name String	The name of the record. Use the value "@" to denote current root domain name. Required for each record.
records.data String	A zone record's value. Required for each record.
records.ttl integer	A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. Required for each record.
records.weight integer	A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type.

Delete a DNS zone

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnszones/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5"

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/dnszones/:id

Delete a DNS zone

The following attributes are returned as part of the response.

Attributes
taskId string	The task id related to the DNS zone deletion.
taskStatus string	The status of the operation.

Import DNS zone records

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnszones/9ae3717a-006a-4aa7-b64b-8bc8d2f2d6e5?operation=import"

Request body example:

{
  "records": [
    {
      "name": "*",
      "type": "NS",
      "ttl": 3600,
      "data": "ns1.above.com.",
      "weight": 1
    }
  ]
}

The above command returns a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/dnszones/:id?operation=import

Import DNS records into a DNS zone in a given environment.

Optional
records Array[Object]	The list of DNS records to import.
records.type String	A zone record's type. Zone record types describe the zone record's behavior. Supported values are A, AAAA, CAA, CNAME, MX, SRV, TXT or NS. Required for each record.
records.name String	The name of the record. Use the value "@" to denote current root domain name. Required for each record.
records.data String	A zone record's value. Required for each record.
records.ttl integer	A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients. Required for each record.
records.weight integer	A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type.

DNS Records

Create and manage your DNS records associated to your zones.

List DNS Records

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnsrecords?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "4eea2e59-8d06-4f37-8fd1-035e3314dxxD",
      "stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95234566",
      "zoneId": "337c7c26-31f4-4b2e-83dc-126exxxxxxWr",
      "name": "test1",
      "type": "A",
      "classCode": "IN",
      "ttl": 21600,
      "data": "127.0.0.0",
      "weight": 1,
      "created": "2021-07-28T17:14:07.928210Z",
      "updated": "2021-07-28T17:14:07.928210Z"
    },
    {
      "id": "0a18b323-72df-447a-af81-08a2ea62re45",
      "stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95234566",
      "zoneId": "337c7c26-31f4-4b2e-83dc-126exxxxxxWr",
      "name": "test2",
      "type": "TXT",
      "classCode": "IN",
      "ttl": 300,
      "data": "123 312 12",
      "weight": 1,
      "created": "2021-07-28T17:14:25.229376Z",
      "updated": "2021-07-28T17:14:25.229376Z"
    }
  ],
  "metadata": {
    "recordCount": 2
  }
}

GET /services/:service_code/:environment_name/dnsrecords?zoneId=:zoneId

Retrieve a list of all DNS records in a given DNS zone in an environment.

Query Params
zoneId UUID	The ID of the zone for which we list the records. This parameter is required.

Attributes
id string	A record's unique identifier.
stackId string	The ID of the stack that a record belongs to.
zoneId string	The ID of zone that the record belongs to.
name string	The name of the record. Use the value "@" to denote current root domain name.
type string	A zone record's type. Zone record types describe the zone record's behavior.
classCode string	A zone record's class code. This is typically "IN" for Internet related resource records.
ttl int	A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients.
data string	A zone record's value.
weight int	A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type.
created string	The date on which the DNS record was created.
updated string	The date on which the DNS record was last updated.

Retrieve a DNS record

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnsrecords/0a18b323-72df-447a-af81-08a2ea62re45?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"

The above command returns a JSON structured like this:

{
  "data": {
      "id": "0a18b323-72df-447a-af81-08a2ea62re45",
      "stackId": "7fbea2c0-17d0-41df-b0b1-4d5c95234566",
      "zoneId": "337c7c26-31f4-4b2e-83dc-126exxxxxxWr",
      "name": "test2",
      "type": "TXT",
      "classCode": "IN",
      "ttl": 300,
      "data": "123 312 12",
      "weight": 1,
      "created": "2021-07-28T17:14:25.229376Z",
      "updated": "2021-07-28T17:14:25.229376Z"
    }
}

GET /services/:service_code/:environment_name/dnsrecords/:id?zoneId=:zoneId

Retrieve a DNS record in a given DNS zone in an environment .

Query Params
zoneId UUID	The ID of the zone for which we want to get the record. This parameter is required.

Attributes
id string	A record's unique identifier.
stackId string	The ID of the stack that a record belongs to.
zoneId string	The ID of zone that the record belongs to.
name string	The name of the record. Use the value "@" to denote current root domain name.
type string	A zone record's type. Zone record types describe the zone record's behavior.
classCode string	A zone record's class code. This is typically "IN" for Internet related resource records.
ttl int	A zone record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients.
data string	A zone record's value.
weight int	A zone record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type.
created string	The date on which the DNS record was created.
updated string	The date on which the DNS record was last updated.

Create a DNS record

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnsrecords?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"

Request body example for creating a DNS record:

{
  "name": "*",
  "type": "NS",
  "ttl": 3600,
  "data": "ns1.above.com.",
  "weight": 1
}

The above command returns a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/dnsrecords?zoneId=:zoneId

Create a DNS record in a given environment.

Query Params
zoneId UUID	The ID of the zone for which we want to create the record. This parameter is required.

Required
name string	The name of the record. Use the value "@" to denote current root domain name.
type string	A DNS record's type. DNS record types describe the record's behavior.
ttl int	A DNS record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients.
data string	A DNS record's value.

Optional
weight int	A DNS record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type.

Update a DNS record

curl -X PUT \
   -H "MC-Api-Key: your_api_key" \
   -d "request_body" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnsrecords/0a18b323-72df-447a-af81-08a2ea62re45?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"

Request body example for creating a DNS record:

{
  "name": "*",
  "type": "NS",
  "ttl": 3600,
  "data": "ns1.above.com.",
  "weight": 1
}

The above command returns a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

PUT /services/:service_code/:environment_name/dnsrecords/:id?zoneId=:zoneId

Update a DNS record in a given environment.

Query Params
zoneId UUID	The ID of the zone for which we want to update the record. This parameter is required.

Required
name string	The name of the record. Use the value "@" to denote current root domain name.
type string	A DNS record's type. DNS record types describe the record's behavior.
ttl int	A DNS record's time to live. A record's TTL is the number of seconds that the record should be cached by DNS resolvers. Use lower TTL values if you expect zone records to change often. Use higher TTL values for records that won't change to prevent extra DNS lookups by clients.
data string	A DNS record's value.

Optional
weight int	A DNS record's priority. A resource record is replicated in StackPath's DNS infrastructure the number of times of the record's weight, giving it a more likely response to queries if a zone has records with the same name and type.

Delete a DNS record

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/api/v1/services/stackpath/test-area/dnsrecords/0a18b323-72df-447a-af81-08a2ea62re45?zoneId=337c7c26-31f4-4b2e-83dc-126exxxxxxWr"

The above command returns a JSON structured like this:

{
  "taskId": "ef70cafa-0544-4709-a66a-c68595ee105a",
  "taskStatus": "SUCCESS"
}

DELETE /services/:service_code/:environment_name/dnsrecords/:id?zoneId=:zoneId

Delete a DNS record.

Query Params
zoneId UUID	The ID of the zone for which we want to delete the record. This parameter is required.

Attributes
taskId string	The task id related to the DNS zone deletion.
taskStatus string	The status of the operation.

Amazon Web Services plugin

The Amazon Web Services (AWS) plugin provides endpoints for carrying out operations on CloudMC compute and networking entities. It also enforces CloudMC's environment-centric multi-tenancy model and RBAC over top of AWS.

Compute

Instances

Deploy and manage your instances.

List instances

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/instances"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "i-03dffc71c7d649bb1",
      "name": "NameOfMyInstance",
      "rootDeviceName": "/dev/xvda",
      "imageId": "ami-0947d2ba12ee1ff75",
      "instanceType": "t2.micro",
      "launchTime": "2022-01-11T20:57:30Z",
      "availabilityZone": "us-east-1a",
      "privateDnsName": "ip-172-31-90-212.ec2.internal",
      "privateIpAddress": "172.31.90.212",
      "publicDnsName": "ec2-54-210-168-154.compute-1.amazonaws.com",
      "publicIpAddress": "54.210.168.154",
      "state": "running",
      "subnetId": "subnet-0ac78483b1159f7e9",
      "vpcId": "vpc-040e8c412dc149b2a",
      "architecture": "x86_64",
      "clientToken": "7fe789d0-1e84-4c6a-886a-828b99f8525b",
      "rootDeviceType": "ebs",
      "virtualizationType": "hvm",
      "tags": [
        {
          "name": "NameOfMyInstance",
          "tag2": "wowASecondValueIdkNotRequired"
        }
      ],
      "coreCount": 1,
      "threadsPerCore": 1,
      "securityGroupName": "default",
      "minCount": 0,
      "maxCount": 0,
      "region": "us-east-1",
      "attachments": [
        {
          "attachTime": "2022-01-11T20:57:31Z",
          "device": "/dev/xvda",
          "instanceId": "i-03dffc71c7d649bb1",
          "state": "attached",
          "volumeId": "vol-0c8dd88e0743c368b",
          "deleteOnTermination": true
        }
      ]
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/instances

Retrieve a list of all instances in a given environment.

Attributes
id string	The ID of the instance.
name string	The name of the instance.
rootDeviceName string	The device name of the root device volume (for example, /dev/sda1 ).
imageId string	The ID of the AMI used to launch the instance.
instanceType string	The instance type.
launchTime string	The time the instance was launched.
availabilityZone string	The Availability Zone of the instance.
privateDnsName string	(IPv4 only) The private DNS hostname name assigned to the instance. This DNS hostname can only be used inside the Amazon EC2 network. This name is not available until the instance enters the running state.
privateIpAddress string	The private IPv4 address assigned to the instance.
publicDnsName string	(IPv4 only) The public DNS name assigned to the instance. This name is not available until the instance enters the running state. For EC2-VPC, this name is only available if you've enabled DNS hostnames for your VPC.
publicIpAddress string	The public IPv4 address, or the Carrier IP address assigned to the instance, if applicable.
state string	The current state of the instance.
subnetId string	[EC2-VPC] The ID of the subnet in which the instance is running.
vpcId string	[EC2-VPC] The ID of the VPC in which the instance is running.
architecture string	The architecture of the image.
clientToken string	The idempotency token you provided when you launched the instance, if applicable.
rootDeviceType string	The root device type used by the AMI. The AMI can use an EBS volume or an instance store volume.
virtualizationType string	The virtualization type of the instance.
tags Array[object]	Any tags assigned to the instance. Tags are key value pairs.
coreCount int	The number of CPU cores for the instance.
threadsPerCore >int	The number of threads per CPU core.
securityGroupName string	The name of the security group.
maxCount integer	The maximum number of instances to create. Cannot be greater than 20.
minCount integer	The minimum number of instances to create. Should be greater than 1.
region string	The region where the instance will be deployed.
attachments Array[object]	The list of volumes to which the instance is attached.

Retrieve an instance

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-03dffc71c7d649bb1"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "i-03dffc71c7d649bb1",
    "name": "NameOfMyInstance",
    "rootDeviceName": "/dev/xvda",
    "imageId": "ami-0947d2ba12ee1ff75",
    "instanceType": "t2.micro",
    "launchTime": "2022-01-11T20:57:30Z",
    "availabilityZone": "us-east-1a",
    "privateDnsName": "ip-172-31-90-212.ec2.internal",
    "privateIpAddress": "172.31.90.212",
    "publicDnsName": "ec2-54-210-168-154.compute-1.amazonaws.com",
    "publicIpAddress": "54.210.168.154",
    "state": "running",
    "subnetId": "subnet-0ac78483b1159f7e9",
    "vpcId": "vpc-040e8c412dc149b2a",
    "architecture": "x86_64",
    "clientToken": "7fe789d0-1e84-4c6a-886a-828b99f8525b",
    "rootDeviceType": "ebs",
    "virtualizationType": "hvm",
    "tags": [
      {
        "name": "NameOfMyInstance",
        "tag2": "wowASecondValueIdkNotRequired"
      }
    ],
    "coreCount": 1,
    "threadsPerCore": 1,
    "securityGroupName": "default",
    "minCount": 0,
    "maxCount": 0,
    "region": "us-east-1",
    "attachments": [
      {
        "attachTime": "2022-01-11T20:57:31Z",
        "device": "/dev/xvda",
        "instanceId": "i-03dffc71c7d649bb1",
        "state": "attached",
        "volumeId": "vol-0c8dd88e0743c368b",
        "deleteOnTermination": true
      }
    ]
  }
}

GET /services/:service_code/:environment_name/instances/:id

Retrieve an instance in a given environment.

Attributes
id string	The ID of the instance.
name string	The name of the instance.
rootDeviceName string	The device name of the root device volume (for example, /dev/sda1 ).
imageId string	The ID of the AMI used to launch the instance.
instanceType string	The instance type.
launchTime string	The time the instance was launched.
availabilityZone string	The Availability Zone of the instance.
privateDnsName string	(IPv4 only) The private DNS hostname name assigned to the instance. This DNS hostname can only be used inside the Amazon EC2 network. This name is not available until the instance enters the running state.
privateIpAddress string	The private IPv4 address assigned to the instance.
publicDnsName string	(IPv4 only) The public DNS name assigned to the instance. This name is not available until the instance enters the running state. For EC2-VPC, this name is only available if you've enabled DNS hostnames for your VPC.
publicIpAddress string	The public IPv4 address, or the Carrier IP address assigned to the instance, if applicable.
state string	The current state of the instance.
subnetId string	[EC2-VPC] The ID of the subnet in which the instance is running.
vpcId string	[EC2-VPC] The ID of the VPC in which the instance is running.
architecture string	The architecture of the image.
clientToken string	The idempotency token you provided when you launched the instance, if applicable.
rootDeviceType string	The root device type used by the AMI. The AMI can use an EBS volume or an instance store volume.
virtualizationType string	The virtualization type of the instance.
tags Array[object]	Any tags assigned to the instance. Tags are key value pairs.
coreCount int	The number of CPU cores for the instance.
threadsPerCore >int	The number of threads per CPU core.
securityGroupName string	The name of the security group.
maxCount integer	The maximum number of instances to create. Cannot be greater than 20.
minCount integer	The minimum number of instances to create. Should be greater than 1.
region string	The region where the instance will be deployed.
attachments Array[object]	The list of volumes to which the instance is attached.

Create an instance

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/instances"

Request body example for an instance with custom security group:

{
  "name": "name-of-the-instance",
  "imageId": "ami-08e4e35cccc6189f4",
  "instanceType": "t2.micro",
  "securityGroupScope": "CUSTOM",
  "securityGroupName": "sc-custom-user-iklp",
  "securityGroupDescription": "Custom: allow only port 8085",
  "minCount": 1,
  "maxCount": 1,
  "region": "us-east-1",
  "sshKey": {
    "keyName": "user ssh key"
  },
  "ipPolicies": [{
    "ipRange": "0.0.0.0/0",
    "protocol": "TCP",
    "portRange": "5200-5220"
  }],
  "blockDeviceMappings": [{
    "type": "Root",
    "attachmentDeviceName": "/dev/xvda",
    "deleteOnTermination": true,
    "size": 30,
    "volumeType": "gp3",
    "iops": 3000,
    "throughput": 250
  }],
  "vpcId": "vpc-0b23fed563eebe635",
  "subnetId": "subnet-0d4d9d813e763d403",
  "volumesToAttach": [{
    "volumeId": "vol-1",
    "device": "/dev/sdg",
  }]
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/instances

Create a new instance in a given environment.

Required
name string	The name of the instance.
region string	The region where the instance will be deployed.
imageId string	The imageId to be used deployed with the instance. Represents the unique identifier of an amazon machine image (AMI). The imageId needs to be compatible with the machine type. The imageId needs to be available in the given region of the instance.
instanceType string	The type of the instance. Represents the specification of the instance (cpu, memory, storage). The instance type needs to be available in the given region of the instance.
securityGroupScope enum	Possible values are CUSTOM, DEFAULT and ALL. Represents the scope of the security group. CUSTOM scope implies that an IP policy will be provided with the payload indicating the custom ports and IP range to use. It indicates that only traffic matching the IP policy will be able to reach the instance. ALL scope allows all traffic from all sources. It is the default scope for an instance. No need to provide an IP policy if that is the selected scope. Default allows HTTP, HTTPS and SSH traffic by opening ports 80, 443 and 22 to all public IPs. No need to provide an IP policy if that is the selected scope.
securityGroupName string	The name of the security group.
securityGroupDescription string	The description of the security group.
maxCount integer	The maximum number of instances to create. Cannot be greater than 20.
minCount integer	The minimum number of instances to create. Should be greater than 1.
sshKey.keyName string	The name of the SSH key to be used to connect to this instance via SSH.
blockDeviceMappings Array	Volumes to attached to the instance on launch. To be left empty if the default root volume should be used.
volumesToAttach Array	Volumes to attached to the instance after it is launched. Only volumes in the same availability zone as the subnet can be attached.

Optional
ipPolicies Array	The IP policy to use for the security group if the security group scope is CUSTOM.
ipPolicies.ipRange string	The IP range in CIDR block notation of an IPV4 compatible string. Indicates the allowed IP(s) to reach the instance.
ipPolicies.protocol enum	Possible values are UDP, TCP and ICMP. Indicates the allowed protocol to use to reach the instance.
ipPolicies.portRange integer	The allowed IP range. Can be a single port or a port range, such as 1024-65535
blockDeviceMappings.type string	Indicates whether the volume is "Root" or "EBS", used to calculate minimum sizing.
blockDeviceMappings.attachmentDeviceName string	The device name for the attached volume.
blockDeviceMappings.deleteOnTermination boolean	Whether or not the volume should be deleted alongside the instance.
blockDeviceMappings.size integer	The required size of the attached volume.
blockDeviceMappings.volumeType string	The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard). Refer to "Create Volume" docs to see volume types & limits for their respective fields.
blockDeviceMappings.iops integer	Describes the maximum number of input/output operations per second (IOPS) supported by the volume type. This field is only valid for volume types gp3, io1, and io2.
blockDeviceMappings.throughput integer	The throughput performance in MiB/s supported by the volume type. This field is only valid for gp3 volumes.
vpcId string	The id of the VPC in which the instance will be deployed. This must be specified if there is no default VPC in the selected region or if you decide to provide a subnet.
subnetId string	The id of the subnet in which the instance will be deployed. If this is not specified, the instance will be deployed in one of the default subnets in the default VPC. The subnet specified must belong to the VPC specified.

Delete an instance

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-0d1f9106cd0e0dff7"

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/instances/:id

Attributes
taskId string	The task id related to the instance deletion.
taskStatus string	The status of the operation.

Start an instance

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-0d1f9106cd0e0dff7?operation=start"

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

START /services/:service_code/:environment_name/instances/:id

Attributes
taskId string	The task id related to the instance to be started.
taskStatus string	The status of the operation.

Stop an instance

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/instances/i-0d1f9106cd0e0dff7?operation=stop"

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

STOP /services/:service_code/:environment_name/instances/:id

Attributes
taskId string	The task id related to the instance to be stopped.
taskStatus string	The status of the operation.

Storage

Volumes

Create an Amazon EBS volume to attach to any EC2 instance in the same Availability Zone.

List Volumes

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/volumes"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "vol-02929c8a1bcbf5f5f",
            "name": "api-volume",
            "attachments": [
              {
                "attachTime": "2022-01-11T20:57:31Z",
                "device": "/dev/xvda",
                "instanceId": "i-03dffc71c7d649bb1",
                "state": "attached",
                "volumeId": "vol-02929c8a1bcbf5f5f",
                "deleteOnTermination": true
              }
            ],
            "availabilityZone": "us-east-1a",
            "createTime": "2020-11-19T03:41:51Z",
            "encrypted": false,
            "size": 1,
            "snapshotId": "",
            "state": "available",
            "volumeId": "vol-02929c8a1bcbf5f5f",
            "iops": 100,
            "tags": [],
            "volumeType": "gp2",
            "fastRestored": false,
            "multiAttachEnabled": false
        }
    ],
    "metadata": {
        "recordCount": 1
    }
}

GET /services/:service_code/:environment_name/volumes

Retrieve a list of all volumes in a given environment.

Attributes
id string	The ID of the volume.
name string	The volume name of the root device volume (for example, /dev/sda1).
attachments Array[object]	The list of instances to which the volume is attached.
availabilityZone string	The Availability Zone of the volume.
createTime string	The timestamp when the volume was created.
encrypted boolean	Indicates whether the volume is encrypted.
size int	The size of the volume in GiB.
snapshotId string	The snapshot from which the volume was created.
state string	The state of the volume (creating, available, in-use, deleting, deleted, error).
volumeId string	The volume ID.
iops int	Describes the maximum number of input/output operations per second (IOPS) that the volume should provide.
tags Array[object]	Any tags assigned to the volume. Tags are key value pairs.
volumeType string	The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard).
fastRestored boolean	Indicates whether the volume was created from a snapshot that is enabled for fast snapshot restore.
multiAttachEnabled boolean	Indicates whether the volume is enabled for Multi-Attach.

Retrieve a volume

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0c8dd88e0743c368b"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "vol-0c8dd88e0743c368b",
    "name": "vol-0c8dd88e0743c368b",
    "attachments": [
      {
          "attachTime": "2022-01-11T20:57:31Z",
          "device": "/dev/xvda",
          "instanceId": "i-03dffc71c7d649bb1",
          "state": "attached",
          "volumeId": "vol-0c8dd88e0743c368b",
          "deleteOnTermination": true
      }
    ],
    "availabilityZone": "us-east-1a",
    "createTime": "2022-01-11T20:57:31.675Z",
    "encrypted": false,
    "size": 8,
    "snapshotId": "snap-0299d083f0ce6cd12",
    "state": "in-use",
    "volumeId": "vol-0c8dd88e0743c368b",
    "iops": 100,
    "tags": [],
    "volumeType": "gp2",
    "fastRestored": false,
    "multiAttachEnabled": false
  }
}

GET /services/:service_code/:environment_name/volumes/:id

Retrieve a volume in a given environment.

Attributes
id string	The ID of the volume.
name string	The volume name of the root device volume (for example, /dev/sda1).
attachments Array[object]	The list of instances to which the volume is attached.
availabilityZone string	The Availability Zone of the volume.
createTime string	The timestamp when the volume was created.
encrypted boolean	Indicates whether the volume is encrypted.
size int	The size of the volume in GiB.
snapshotId string	The snapshot from which the volume was created.
state string	The state of the volume (creating, available, in-use, deleting, deleted, error).
volumeId string	The volume ID.
iops int	Describes the maximum number of input/output operations per second (IOPS) that the volume should provide.
tags Array[object]	Any tags assigned to the volume. Tags are key value pairs.
volumeType string	The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard).
fastRestored boolean	Indicates whether the volume was created from a snapshot that is enabled for fast snapshot restore.
multiAttachEnabled boolean	Indicates whether the volume is enabled for Multi-Attach.

Create Volume

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/volumes"

Request body example for a volume: json { "name": "api-volume", "availabilityZone": "us-east-1a", "size": 1, "iops": 100, "throughput": 125, "volumeType": "gp3", "multiAttachEnabled": false }

The above command returns a JSON structured like this:

{
    "taskId": "35d38672-8772-4b04-b1ca-1b13b97638ca",
    "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/volumes

Retrieve a list of all volumes in a given environment.

Attributes
availabilityZone string	The Availability Zone of the volume within the service connection's default region policy.
size int	The size of the volume in GiB. Size is a required field for all volume types.
volumeType string	The Amazon EBS volume type. Below is a list of the possible volume types and the limits for their respective fields.

• gp2 (1-16,384 GiB Size)
• gp3 (1-16,384 GiB Size, 3,000-16,000 IOPS, 125-1000 MiB/s Throughput)
• io1 (4-16,384 GiB Size, 100-64,000 IOPS, 50:1 IOPS/GiB ratio)
• io2 (4-16,384 GiB Size, 100-256,000 IOPS, 1000:1 IOPS/GiB ratio)
• sc1 (125-16,384 GiB Size)
• sc2 (125-16,384 GiB Size)
• standard (1-1,024 GiB Size)

Optional
name string	The volume name. A default name will be created if there isn't one provided.
iops int	Describes the maximum number of input/output operations per second (IOPS) that the volume should provide. This field is only valid for gp3, io1, and io2 volume types. It is mandatory for io1 and io2 volumes.
throughput int	The throughput performance in MiB/s that the volume can support. This field is required for gp3 volumes.
multiAttachEnabled boolean	Indicates whether the volume is enabled for Multi-Attach. This is only supported for io1 and io2 volume types.

Modify Volume

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0c8dd88e0743c368b"

Request body example for a volume: json { "name": "api-volume", "id": "vol-0c8dd88e0743c368b", "size": 1, "iops": 100, "throughput": 125, "volumeType": "gp3", "multiAttachEnabled": false, "attachments": [ { "attachTime": "2022-01-11T20:57:31Z", "device": "/dev/xvda", "instanceId": "i-03dffc71c7d649bb1", "state": "attached", "volumeId": "vol-0c8dd88e0743c368b", "deleteOnTermination": true } ] } The above command returns a JSON structured like this:

{
    "taskId": "35d38672-8772-4b04-b1ca-1b13b97638ca",
    "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/volumes/:id

Modify a volume in a given environment environment.

Attributes
id string	The ID of the volume.
name string	The volume name of the root device volume (for example, /dev/sda1).
attachments Array[object]	The list of instances to which the volume is attached.
size int	The size of the volume in GiB.
volumeId string	The volume ID.
iops int	Describes the maximum number of input/output operations per second (IOPS) that the volume should provide.
volumeType string	The Amazon EBS volume type (gp2, gp3, io1, io2, st1, sc1, standard).
multiAttachEnabled boolean	Indicates whether the volume is enabled for Multi-Attach.

Delete a volume

Note: only volumes in an "available" state can be deleted

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0d1f9106cd0e0dff7"

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/volumes/:id

Attributes
taskId string	The task id related to the instance deletion.
taskStatus string	The status of the operation.

Attach a volume

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0d1f9106cd0e0dff7?operation=attach"

Request body example for a volume: json { "instanceIdToAttach": "i-0b4e945ee65072b8a", "attachmentDeviceName": "/dev/sda1" } | Attributes |   | |----------------------------|-------------------------------------------------| | instanceIdToAttach
string | Id of the instance the volume will be attached to (must be in the same availability zone). | | attachmentDeviceName
string | The device name that you assign is used by Amazon EC2. The device names that you're allowed to assign depends on the virtualization type of the selected instance. | - Linux device names: /dev/sdf through /dev/sdp - Windows device names: /dev/xvdf through /dev/xvdz - Linux root device names: /dev/sda1 or /dev/xvda (depending on the AMI) - Windows root device names: /dev/sda1

The above command returns a JSON structured like this: json { "taskId": "c8f44de4-e36f-456d-9802-3fb59cce3de2", "taskStatus": "PENDING" }

POST /services/:service_code/:environment_name/volumes/:id

Attributes
taskId string	The task id related to the instance attachment.
taskStatus string	The status of the operation.

Detach a volume

Note: Only attached volumes can be detached. Detaching a root device volume will result in stopping the instance before detaching the volume.

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-area/volumes/vol-0d1f9106cd0e0dff7?operation=detach"

Request body example for a volume: json { "instanceIdToDetach": "i-0e0d3jh110d1f9106" }

The above command returns a JSON structured like this: json { "taskId": "30121175-926a-4fd2-991b-ff303ffdf905", "taskStatus": "PENDING" }

POST /services/:service_code/:environment_name/volumes/:id

Attributes
taskId string	The task id related to the instance detachment.
taskStatus string	The status of the operation.

S3

Buckets

View and manage your buckets.

Retrieve a Bucket

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/buckets/us-east-1/bucket-nsturk-lullp"

The above command returns a JSON structured like this:

{
    "data": {
        "size": 123123,
        "keyCount": 4,
        "id": "us-east-1/bucket-nsturk-lullp",
        "name": "bucket-nsturk-lullp",
        "region": "us-east-1",
        "created": "Tue Mar 22 16:15:03 UTC 2022",
        "url": "https://bucket-nsturk-lullp.s3.us-east-1.amazonaws.com/",
        "access": "private"
    }
}

GET /services/:service_code/:environment_name/buckets/:regionName/:bucketName

Retrieve a list of all buckets from Amazon S3.

Attributes
id string	The ID of the bucket, which is of the form :regionName/:bucketName.
name string	The name of the bucket.
region string	The region the bucket exists in.
created string	The date the bucket was created.
url string	The full endpoint URL used to make API calls on the bucket.
size integer	The size of the bucket in bytes. Omitted if query parameter details=false.
keyCount integer	The number of objects inside the bucket. Omitted if query parameter details=false.

Optional Query Parameters
details boolean	Whether to include more details about the bucket, if omitted defaults to true and returns extra parameters size and keyCount.

List Buckets

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/buckets"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "id": "us-east-1/bucketOne",
            "name": "bucketOne",
            "region": "us-east-1",
            "created": "Tue Mar 01 16:13:29 EST 2022",
            "url": "https://bucketOne.s3.amazonaws.com/"
        },
        {
            "id": "ap-south-1/bucketTwo",
            "name": "bucketTwo",
            "region": "ap-south-1",
            "created": "Fri Mar 04 16:20:29 EST 2022",
            "url": "https://bucketTwo.s3.amazonaws.com/"
        }
    ],
    "metadata": {
        "recordCount": 2
    }
}

GET /services/:service_code/:environment_name/buckets

Retrieve a list of all buckets from Amazon S3.

Attributes
id string	The ID of the bucket, which is of the form :regionName/:bucketName.
name string	The name of the bucket.
region string	The region the bucket exists in.
created string	The date the bucket was created.
url string	The full endpoint URL used to make API calls on the bucket.

Create Bucket

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/buckets"

Request body examples:

{
  "access": "private",
  "name": "bucket-root-agejo",
  "region": "us-east-1",
}

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/buckets?operation=create

Create a bucket in Amazon S3.

Required
access string	The desired access level of the bucket. The list of supported Canned ACL is: private, public-read, public-read-write, authenticated-read, log-delivery-write, aws-exec-read.
name string	The name of the bucket.
region string	The region to create the bucket in.

Attributes
taskId string	The task ID related to the bucket creation.
taskStatus string	The status of the operation.

Update Bucket Permissions

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/buckets/:regionName/:bucketName?operation=edit_privileges"

Request body examples:

{
    "access": "public-read"
}

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/buckets/:regionName/:bucketName?operation=edit_privileges

Update the canned ACL of a buckets from Amazon S3.

Required
access string	The name of the Canned ACL to be assigned to the bucket. The list of supported Canned ACL is: private, public-read, public-read-write, authenticated-read, log-delivery-write, aws-exec-read.

Attributes
taskId string	The task ID related to the bucket creation.
taskStatus string	The status of the operation.

Delete Bucket

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/buckets/us-east-1/bucketOne"

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/buckets/:regionName/:bucketName

Attributes
taskId string	The task ID related to the bucket deletion.
taskStatus string	The status of the operation.

Objects

View and manage your objects within a bucket.

Retrieve an Object

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/objects/us-east-1/bucket-nsturk-lullp/photos/miami.png"

The above command returns a JSON structured like this:

{
    "data": {
        "name": "miami.png",
        "id": "us-east-1/bucket-nsturk-lullp/photos/miami.png",
        "size": 35186,
        "fullPath": "photos/miami.png",
        "storageClass": "STANDARD",
        "lastModified": "Mon Mar 21 14:15:05 EDT 2022",
        "displaySize": {
            "value": "34.4",
            "unitKey": "units.filesizes.KB"
        },
        "contentType": "image/png",
        "eTag": "a8b886246bccda023fbb348731c1bd05",
        "isFolder": false,
        "bucketName": "bucket-nsturk-lullp",
        "region": "us-east-1",
        "isVirtual": false
    }
}

GET /services/:service_code/:environment_name/objects/:regionName/:bucketName/:pathToObject

Retrieve a list of objects inside a given folder inside a given bucket.

Attributes
id string	The ID of the object, which is of the form :regionName/:bucketName/:objectName.
name string	The name of the object.
fullPath string	The actual key of the object inside the bucket, which is represented as a full path.
size integer	The size of the object in bytes.
storageClass string	The type of storage class on the object.
lastModified string	The date the object was last updated.
displaySize string	The size of the object represented as an object in either KB, MB, or GB.
contentType string	The type of file.
eTag string	The eTag of the object generated by S3 during initial upload.
isFolder boolean	Boolean value denoting whether the object acts as a folder. This is always true when the fullPath attribute ends with a '/' character.
bucketName string	The name of the bucket the object exists within.
region string	The name of the region the object exists within.
isVirtual boolean	Boolean value denoting whether the folder is virtual. If true there exists no object named :folderName/, and the folder exists only as a part of a complete object path (:folderName/:objectName). If false, there exists a key in the bucket named ‘{folderName}/’. If the query parameter nested = true, the request will not return any virtual folders.

List Objects

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/objects?bucketId=us-east-1/bucket-root-brdje"

The above command returns a JSON structured like this:

{
    "data": [
        {
            "name": "cat.jpeg",
            "id": "us-east-1/bucket-root-nvisf/photos/cat.jpeg",
            "size": 35186,
            "fullPath": "photos/cat.jpeg",
            "storageClass": "STANDARD",
            "lastModified": "Mon Mar 21 14:15:05 EDT 2022",
            "displaySize": {
                "value": "34.4",
                "unitKey": "units.filesizes.KB"
            },
            "contentType": "image/jpeg",
            "eTag": "a8b886246bccda023fbb348731c1bd05",
            "isFolder": false,
            "bucketName": "bucket-root-nvisf",
            "region": "us-east-1",
            "isVirtual": false
        },
        {
            "name": "miami",
            "id": "us-east-1/bucket-root-nvisf/photos/miami/",
            "fullPath": "photos/miami/",
            "contentType": "application/directory",
            "eTag": "",
            "isFolder": true,
            "bucketName": "bucket-root-nvisf",
            "region": "us-east-1",
            "isVirtual": false
        },
        {
            "name": "vegas",
            "id": "us-east-1/bucket-root-nvisf/photos/vegas/",
            "fullPath": "photos/vegas/",
            "contentType": "application/directory",
            "eTag": "",
            "isFolder": true,
            "bucketName": "bucket-root-nvisf",
            "region": "us-east-1",
            "isVirtual": false
        }
    ],
    "metadata": {
        "recordCount": 3
    }
}

GET /services/:service_code/:environment_name/objects?bucketId=:regionName/:bucketName

Retrieve a list of objects inside a given folder inside a given bucket.

Attributes
id string	The ID of the object, which is of the form :regionName/:bucketName/:objectName.
name string	The name of the object.
fullPath string	The actual key of the object inside the bucket, which is represented as a full path.
size integer	The size of the object in bytes.
storageClass string	The type of storage class on the object.
lastModified string	The date the object was last updated.
displaySize string	The size of the object represented as an object in either KB, MB, or GB.
contentType string	The type of file.
eTag string	The eTag of the object generated by S3 during initial upload.
isFolder boolean	Boolean denoting whether the object acts as a folder. This is always true when the fullPath attribute ends with a '/' character.
bucketName string	The name of the bucket the object exists within.
region string	The name of the region the object exists within.
isVirtual boolean	Boolean value denoting whether the folder is virtual. If true there exists no object named :folderName/, and the folder exists only as a part of a complete object path (:folderName/:objectName). If false, there exists a key in the bucket named ‘{folderName}/’. If the query parameter nested = true, the request will not return any virtual folders.

Required Query Parameters
bucketId string	The ID of the bucket of the form :regionName/:bucketName.

Optional Query Paramaters
prefix string	The path of the objects to search in. If prefix is left blank, it will search for objects in the root. If nested = true and prefix is left blank, it will obtain all objects in the bucket.
nested boolean	Whether to include nested objects or just include objects in the root of the prefix. If nested = true, the request will not return any virtual folders.

Upload Object

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/operation/upload" \
   --form operation=upload \
   --form entityType=objects \
   --form serviceConnectionId=connection_id \
   --form environmentId=environment_id \
   --form filename=file_size \
   --form bucketName=bucket_name \
   --form regionName=region_name \
   --form file=path_to_file

Request body examples as Multipart Form:

operation: upload
entityType: objects
serviceConnectionId: connection_id
environmentId: environment_id
filename: file_size
bucketName: bucket_name
regionName: region_name
file: path_to_file

The above command returns a JSON structured like this:

{
    "files": [
        {
            "name": "filename.png",
            "size": 93240,
            "status": "success"
        }
    ]
}

POST /rest/services/operations/upload

Upload a file to a bucket in Amazon S3.

Required
operation string	The type of operation to execute, in this case upload.
entityType string	The entityType, in this case objects.
serviceConnectionId string	The ID tied to the related service connection.
environmentId string	The ID tied to the related environment.
bucketName string	The name of the bucket to upload the file to.
regionName string	The name of the region to upload the file to.
:fileName long	Key should be the name of the file and value should be the size of the file in bytes.
file string	The path to the file. This needs to be the last parameter in the form.

Attributes
name string	The name of the file uploaded.
size integer	The size of the file uploaded.
status string	String indicating the status of the operation.

Download Object

curl --request GET \
  -H "MC-Api-Key: your_api_key" \
  "https://cloudmc_endpoint/rest/services/operations/:service_connection_id/download?bucketName=akc-buck&regionName=us-east-1&id=us-east-1/akc-buck/api123.png&entityType=objects&operation=download&environmentId=97430433-875c-4ba5-8c57-90a051a52729"

GET rest/services/operations/:service_connection_id/download?id=:regionName/:bucketName/:objectPath&entityType=objects&operation=download&environmentId:environmentId

Download an object from a bucket in Amazon S3.

The above command returns the binary that represent the file downloaded.

Required Query Parameters
id string	The ID of the object to download, which is of the form ":regionName/:bucketName/:objectName".
entityType string	The type of entity to download. In this case objects.
environmentId string	The ID of environment which owns the object.

Delete Object

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject/?operation=delete"

Request body examples:

{
  "id": "ap-south-1/bucket-root-dwyak/images/",
}

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/objects/:regionName/:bucketName/:fullPath

Delete an object from a bucket in Amazon S3.

Attributes
taskId string	The task ID related to the object deletion.
taskStatus string	The status of the operation.

Rename Object

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject/?operation=rename"

Rename an object in a bucket in Amazon S3.

Request body examples:

{
  "name": "newFilePath.png",
}

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

POST /services/operation/rename :service_code/:environment_name/objects/:regionName/:bucketName/:fullPath?&operation=rename

Required
name string	The new name of the object.

Attributes
taskId string	The task ID related to the object renaming.
taskStatus string	The status of the operation.

Add Folder

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/objects/?bucketName=bucketOne&regionName=regionOne&operation=add_folder"

Add a folder in amazon S3.

Request body examples:

{
  "name": "newFolderName",
}

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

POST /services/operation/rename :service_code/:environment_name/objects/?bucketName=:bucketName&regionName=:regionName&operation=add_folder

Required
name string	The name of the folder. Can contain '/' characters to create nested folders.

Attributes
taskId string	The task ID related to the folder creation.
taskStatus string	The status of the operation.

Required Query Parameters
bucketName string	The name of the bucket to create the folder in.
regionName string	The name of the region the bucket exists in.

Optional Query Parameters
prefix string	The folder path to create the folder in. If omitted, a folder will be created in the root of the bucket.

Rename Folder

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject?&operation=rename_folder"

Renames a folder in Amazon S3. This operation renames all objects inside the folder to use the new folder name and their full path. To accomplish this, all objects must first be copied with a new key, then deleted. This operation can take an extended amount of time depending on the amount and size of objects inside the folder.

Request body examples:

{
  "name": "newFolderName",
}

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/objects/:regionName/:bucketName/:folderFullPath?&operation=rename_folder

Required
name string	The new name of the folder. Can contain '/' characters to create nested folders.

Attributes
taskId string	The task ID related to the folder renaming.
taskStatus string	The status of the operation.

Generate URL

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/rest/services/aws/test-env/objects/:regionName/:bucketName/:pathToObject?&operation=generate_url"

Generates a presigned URL in S3. Must specify a limit in the request which denotes the amount of time (in minutes) until the URL expires. Minimum is 1 minute and maximum is 10080 minutes.

Request body examples:

{
  "limit": "60",
}

The above command returns a JSON structured like this:

{
    "taskId": "30121175-926a-4fd2-991b-ff303ffdf905",
    "taskStatus": "SUCCESS"
}

POST /services/:service_code/:environment_name/objects/:regionName/:bucketName/:objectFullPath?&operation=generate_url

Required
limit integer	The length (in minutes) the link will be active for.

Attributes
taskId string	The task ID related to the URL generation.
taskStatus string	The status of the operation.

Networking

Virtual Private Clouds

View and manage vpcs.

List VPCs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/vpcs"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "vpc-0fc6135adfbe4a69c",
      "name": "vpc-0fc6135adfbe4a69c",
      "ownerId": "187065266101",
      "instanceTenancy": "default",
      "cidrBlock": "172.31.0.0/16",
      "dhcpOptionsId": "dopt-04a202f0ccfc4ecb2",
      "state": "available",
      "isDefault": true
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/vpcs

Retrieve a list of all vpcs in a given environment.

Attributes
id string	The ID of the VPC.
name string	The name of the VPC.
ownerId string	Amazon account id of organization owner.
instanceTenancy string	The tenancy options for instances launched into the VPC (default, dedicated, host), set as shared by default.
cidrBlock string	IPv4 network range for the VPC in CIDR notation.
dhcpOptionsId string	The DHCP options set applied to the network configuration of the VPC.
state string	The state of VPC access (pending, available).
isDefault boolean	Whether or not the VPC is the default environment VPC.

Retrieve a VPC

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/vpcs/vpc_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "vpc-0fc6135adfbe4a69c",
    "name": "vpc-0fc6135adfbe4a69c",
    "ownerId": "187065266101",
    "instanceTenancy": "default",
    "cidrBlock": "172.31.0.0/16",
    "dhcpOptionsId": "dopt-04a202f0ccfc4ecb2",
    "state": "available",
    "isDefault": true
  }
}

GET /services/:service_code/:environment_name/vpcs/:id

Retrieve a vpc in a given environment.

Attributes
id string	The ID of the VPC.
name string	The name of the VPC.
ownerId string	Amazon account id of organization owner.
instanceTenancy string	The tenancy options for instances launched into the VPC (default, dedicated, host), set as shared by default.
cidrBlock string	IPv4 network range for the VPC in CIDR notation.
dhcpOptionsId string	The DHCP options set applied to the network configuration of the VPC.
state string	The state of VPC access (pending, available).
isDefault boolean	Whether or not the VPC is the default environment VPC.

Create a VPC

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/vpcs"

Request body example for a named VPC:

{
  "name": "name-of-the-vpc",
  "cidrBlock": "10.0.0.0/24"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

GET /services/:service_code/:environment_name/vpcs

Create a VPC in a given environment.

Attributes
id string	The ID of the VPC.

Optional
name string	The VPC name. A default name will be created if there isn't one provided.

Delete a VPC

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/vpcs/vpc-05a6af2e6a6360915"

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/vpcs/:id

Delete a VPC in a given environment.

Attributes
taskId string	The task id related to the VPC deletion.
taskStatus string	The status of the operation.

Subnetworks

Subnets are a range of IP addresses within your VPC. You can use a public subnet for resources that that will be connected to the internet, and a private subnet for resources that won't be. The CIDR block of a subnet can be the same as the CIDR block for the VPC (for a single subnet in the VPC), or a subset of the CIDR block for the VPC (to create multiple subnets in the VPC). The allowed block size is between a /28 netmask and /16 netmask. If you create more than one subnet in a VPC, the CIDR blocks of the subnets cannot overlap. Each subnet must be associated with a route table, which specifies the allowed routes for outbound traffic leaving the subnet. Every subnet that you create is automatically associated with the main route table for the VPC.

List Subnets

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/subnetworks"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "name": "subnet-0b9cd03ba220cff0c",
      "id": "subnet-0b9cd03ba220cff0c",
      "cidrBlock": "172.31.32.0/20",
      "availabilityZone": "us-east-1c",
      "defaultSubnet": true,
      "state": "available",
      "subnetARN": "arn:aws:ec2:us-east-1:559465017721:subnet/subnet-0b9cd03ba220cff0c",
      "routeTableId": "rtb-0ffdc3e3c20fb0246",
      "availabilityZoneId": "use1-az6",
      "resourceNameDNSARecordEnabled": false,
      "dns64Enabled": false,
      "autoAssignIPv4Address": true,
      "autoAssignCustomerOwnedIPv4Address": false,
      "ipv4CIDRReservations": false,
      "availableIPv4Addresses": 4091,
      "vpcId": "vpc-040e8c412dc149b2a"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/subnetworks

Retrieve a list of all subnets in a given environment.

Attributes
name string	The name of the subnet. (ID if not set)
id string	The id of the subnet.
cidrBlock string	IPv4 network range for the subnet in CIDR.
availabilityZone string	The availability zone of the subnet.
defaultSubnet boolean	If the subnet is the default for its availability zone.
state string	State of the subnet. (pending, availabile)
subnetARN string	The Amazon Resource Name (ARN) of the subnet.
routeTableId string	ID of the route table associated with the subnet.
availabilityZoneId string	The ID of the subnet's availability zone.
resourceNameDNSARecordEnabled boolean	Indicates whether to respond to DNS queries for instance hostnames with DNS A records.
dns64Enabled boolean	Indicates if DNS queries made to the resolver in this subnet should return synthetic IPv6 addresses for IPv4-only destinations.
autoAssignIPv4Address boolean	Indicates whether instances launched in this subnet receive a public IPv4 address.
autoAssignCustomerOwnedIPv4Address boolean	Indicates whether a network interface created in this subnet receives a customer-owned IPv4 address.
ipv4CIDRReservations boolean	Indicates whether the subnet has IPv4 CIDR reservations.
availableIPv4Addreses int	The number of available addresses in the subnet's CIDR block.
vpcId string	The ID of the VPC the subnet is associated with.

Retrieve a Subnet

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/subnetwork/subnet_id"

The above command returns a JSON structured like this:

{
  "data": {
    "name": "subnet-0b9cd03ba220cff0c",
    "id": "subnet-0b9cd03ba220cff0c",
    "cidrBlock": "172.31.32.0/20",
    "availabilityZone": "us-east-1c",
    "defaultSubnet": true,
    "state": "available",
    "subnetARN": "arn:aws:ec2:us-east-1:559465017721:subnet/subnet-0b9cd03ba220cff0c",
    "routeTableId": "rtb-0ffdc3e3c20fb0246",
    "availabilityZoneId": "use1-az6",
    "resourceNameDNSARecordEnabled": false,
    "dns64Enabled": false,
    "autoAssignIPv4Address": true,
    "autoAssignCustomerOwnedIPv4Address": false,
    "ipv4CIDRReservations": false,
    "availableIPv4Addresses": 4091,
    "vpcId": "vpc-040e8c412dc149b2a"
  }
}

GET /services/:service_code/:environment_name/subnetworks/:id

Retrieve a subnetwork in a given environment.

Attributes
name string	The name of the subnet. (ID if not set)
id string	The id of the subnet.
cidrBlock string	IPv4 network range for the subnet in CIDR.
availabilityZone string	The availability zone of the subnet.
defaultSubnet boolean	If the subnet is the default for its availability zone.
state string	State of the subnet. (pending, availabile)
subnetARN string	The Amazon Resource Name (ARN) of the subnet.
routeTableId string	ID of the route table associated with the subnet.
availabilityZoneId string	The ID of the subnet's availability zone.
resourceNameDNSARecordEnabled boolean	Indicates whether to respond to DNS queries for instance hostnames with DNS A records.
dns64Enabled boolean	Indicates if DNS queries made to the resolver in this subnet should return synthetic IPv6 addresses for IPv4-only destinations.
autoAssignIPv4Address boolean	Indicates whether instances launched in this subnet receive a public IPv4 address.
autoAssignCustomerOwnedIPv4Address boolean	Indicates whether a network interface created in this subnet receives a customer-owned IPv4 address.
ipv4CIDRReservations boolean	Indicates whether the subnet has IPv4 CIDR reservations.
availableIPv4Addreses int	The number of available addresses in the subnet's CIDR block.
vpcId string	The ID of the VPC the subnet is associated with.

Delete a Subnetwork

curl -X DELETE \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/subnetworks/subnet-07baec16047092451"

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

DELETE /services/:service_code/:environment_name/subnetworks/:id

Delete a Subnetwork in a given environment.

Attributes
taskId string	The task id related to the subnet deletion.
taskStatus string	The status of the operation.

Internet Gateways

An internet gateway is a VPC child component that allows communication between your VPC and the internet. An internet gateway enables resources in your public subnets to connect to the internet if the resource has a public IPv4 address or an IPv6 address.

List Internet Gateways

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/internetgateways"

The above command returns a JSON structured like this: json { "data": [ { "id": "igw-03d0a0c6cb0d12279", "name": "my-internet-getaway", "state": "ATTACHED", "vpcId": "vpc-03326d9953f72ec19" }, { "id": "igw-06d73b330ef63d750", "name": "my-internet-gateway", "state": "ATTACHED", "vpcId": "vpc-0094a0760c22437ec" }, { "id": "igw-077302734797e7b3e", "name": "project-igw", "state": "ATTACHED", "vpcId": "vpc-0d9134bbb657cc1e3" }, { "id": "igw-09f61d7c642156d6e", "name": "igw-09f61d7c642156d6e", "state": "DETACHED" } ], "metadata": { "recordCount": 4 } }

GET /services/:service_code/:environment_name/internetgateways

Optional Query Parameters
vpcId string	Filter Internet Gateways by VPC Identifier

Retrieve a list of all internet gateways.

Attributes
id string	The ID of the Internet Gateway.
name string	The name of the Internet Gateway, which is derived from a Tag with the Name key.
state string	The state of the Internet Gateway depending whether or not it is attached or not to a VPC. The possible values include: ATTACHED, DETACHED.
vpcId string	The identifier of the VPC, if attached. Else this field is not returned

Retrieve an Internet Gateway

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test/internetgateways/igw-03d0a0c6cb0d12279"

The above command returns a JSON structured like this:

{
    "data": {
        "id": "igw-03d0a0c6cb0d12279",
        "name": "my-internet-getaway",
        "state": "ATTACHED",
        "vpcId": "vpc-03326d9953f72ec19"
    }
}

GET /services/:service_code/:environment_name/internetgateways/:id

Retrieve an internet gateway in a given environment.

Attributes
id string	The ID of the Internet Gateway.
name string	The name of the Internet Gateway, which is derived from a Tag with the Name key.
state string	The state of the Internet Gateway depending whether or not it is attached or not to a VPC. The possible values include: ATTACHED, DETACHED.
vpcId string	The identifier of the VPC, if attached. Else this field is not returned.

Create an Internet Gateway

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/aws-tesv/internetgateways?operation=create"

Request body example to create an internet gateway:

{
  "name": "igw-root-guthc",
  "vpcId": "vpc-0094a0760c22437ec"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/internetgateways

Create a new internet gateway in a DETACHED state in a given environment.

Optional
name string	The name of the internet gateway. Automatically generated if not provided.
vpcId string	The ID of the VPC.

Attach an Internet Gateway

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/aws-tesv/internetgateways/igw-09adee4bafdef2c31?operation=attach"

Request body example to attach an internet gateway:

{
  "vpcId": "vpc-0094a0760c22437ec",
  "cidrBlock": "0.0.0.0/0"
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/internetgateways/:id

Attach an internet gateway to a VPC in a given environment.

Required
vpcId string	The ID of the VPC.
cidrBlock string	The CIDR IPv4 Block for the route of the Internet Gateway.

Detach an Internet Gateway

curl -X POST \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/aws-tesv/internetgateways/igw-09adee4bafdef2c31?operation=detach"

Request body example to detach an internet gateway:

{
  "vpcId": "vpc-0ebb01212fbb562a3",
  "deleteRoutes": true
}

The above commands return a JSON structured like this:

{
  "taskId": "7135ae25-8488-4bc5-a289-285c84a00a84",
  "taskStatus": "PENDING"
}

POST /services/:service_code/:environment_name/internetgateways/:id

Detach an internet gateway from a VPC in a given environment.

Required
vpcId string	The ID of the VPC.
deleteRoutes boolean	Whether or not to delete the routes attached to the Internet Gateway. Default to true.

Elastic IPs

An Elastic IP address is a static public IPv4 formatted address designed to be dynamically associated with an instance. By using an Elastic IP address, upon failure of its associated instance, the address will be remapped to a new instance within your account.

List Elastic IPs

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/elasticips"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "eipalloc-0d3879198406bdbd7",
      "name": "eipalloc-0d3879198406bdbd7",
      "associationId": "eipassoc-0c6e3aecfb15418c2",
      "domain": "VPC",
      "instanceId": "i-006d9b167ae39a16f",
      "instanceName": "instance",
      "networkBorderGroup": "us-east-1",
      "networkInterfaceId": "eni-0695dc329b83787e2",
      "privateIpAddress": "10.0.0.172",
      "publicIp": "44.194.69.77",
      "state": "ASSOCIATED"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/elasticips

Retrieve a list of all elastic ips in a given environment.

Attributes
id string	The ID of the Elastic IP.
name string	The name of the Elastic IP.
associationId string	The ID of the association between the Elastic IP and instance.
domain string	Indicates whether this Elastic IP address is for use with instances in EC2-Classic (standard) or instances in a VPC (vpc).
instanceId string	The ID of the instance that the address is associated with (if any).
instanceName string	The name of the instance that the address is associated with (if any).
networkBorderGroup string	The name of the unique set of Availability Zones, Local Zones, or Wavelength Zones from which AWS advertises IP addresses.
networkInterfaceId boolean	The ID of the network interface.
privateIpAddress boolean	The private IP address associated with the Elastic IP address.
publicIp boolean	The Elastic IP address.
state boolean	The attachment state of the Elastic IP. Can be either Associated or Available.

Retrieve an Elastic IP

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/elasticips/elasticip_id"

The above command returns a JSON structured like this:

{
  "data": {
    "id": "eipalloc-0d3879198406bdbd7",
    "name": "eipalloc-0d3879198406bdbd7",
    "associationId": "eipassoc-0c6e3aecfb15418c2",
    "domain": "VPC",
    "instanceId": "i-006d9b167ae39a16f",
    "instanceName": "instance",
    "networkBorderGroup": "us-east-1",
    "networkInterfaceId": "eni-0695dc329b83787e2",
    "privateIpAddress": "10.0.0.172",
    "publicIp": "44.194.69.77",
    "state": "ASSOCIATED"
  }
}

GET /services/:service_code/:environment_name/elasticips/:id

Retrieve an elastic ip in a given environment.

Attributes
id string	The ID of the Elastic IP.
name string	The name of the Elastic IP.
associationId string	The ID of the association between the Elastic IP and instance.
domain string	Indicates whether this Elastic IP address is for use with instances in EC2-Classic (standard) or instances in a VPC (vpc).
instanceId string	The ID of the instance that the address is associated with (if any).
instanceName string	The name of the instance that the address is associated with (if any).
networkBorderGroup string	The name of the unique set of Availability Zones, Local Zones, or Wavelength Zones from which AWS advertises IP addresses.
networkInterfaceId boolean	The ID of the network interface.
privateIpAddress boolean	The private IP address associated with the Elastic IP address.
publicIp boolean	The Elastic IP address.
state boolean	The attachment state of the Elastic IP. Can be either Associated or Available.

CIDR Blocks

A Classless Inter-Domain Routing (CIDR) block has to be associated to a VPC. Therefore, you need to provide the VPC ID in order to fetch the CIDR blocks.

Get CIDR Blocks by VPC

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/cidrblocks?vpcId=:vpc_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "172.31.0.0/16",
      "state": "ASSOCIATED",
      "addressType": "IPv4"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/cidrblocks

Required Query Parameters
vpcId string	Get CIDR block by VPC identifier

Retrieve a list of all CIDR block attached to the VPC.

Attributes
id string	The CIDR Block
state string	The state of the CIDR. The possible values include: ASSOCIATING, ASSOCIATED, DISASSOCIATING, DISASSOCIATED, FAILING, FAILED
addressType string	The type of Address. The possible values include: IPv4

CIDR Reservations

A range of allowed IPv4 addresses in a subnet.

Get CIDR Reservations by Subnet

curl -X GET \
   -H "MC-Api-Key: your_api_key" \
   "https://cloudmc_endpoint/v1/services/aws/test-env/cidrreservations?subnetId=:subnet_id"

The above command returns a JSON structured like this:

{
  "data": [
    {
      "id": "scr-062b86003e2a05fd1",
      "cidrBlock": "10.0.1.0/24",
      "reservationType": "prefix",
      "subnetId": "subnet-0b66921f149046e14"
    }
  ],
  "metadata": {
    "recordCount": 1
  }
}

GET /services/:service_code/:environment_name/cidrreservations

Required Query Parameters
subnetID string	Get CIDR block by Subnet identifier

Retrieve a list of all CIDR reservations associated to the Subnet.

Attributes
id string	The CIDR Reservation ID
cidrBlock string	The associated CIDR block
addressType string	The address reservation type (prefix, explicit)